how-tos

Gemini 4 Carbon API: guia do primeiro pedido em cURL, Python e Gemini Native

Poyo.ai Team
10 min read
Share:

Guia da Gemini 4 Carbon API: primeiro pedido em cURL e Python

Este guia da Gemini 4 Carbon API leva-te de uma chave de API até um pedido funcional em cURL, com o SDK Python da OpenAI e no formato nativo generateContent da Google, sempre com o ID de modelo gemini-4-carbon. Cada exemplo segue o esquema de pedido publicado pelo PoYo à data de 16 de novembro de 2026. Podes testar primeiro os prompts na página do modelo Gemini 4 Carbon.

É a primeira vez que usas o modelo? Começa pela visão geral da Gemini 4 Carbon API para conheceres os limites e o posicionamento.

Antes de começar

Cria uma chave no painel do PoYo e mantém-na no teu servidor:

export POYO_API_KEY="your-poyo-key"
FormatoEndpointUsa-o quando
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsJá usas o SDK da OpenAI, mensagens só de texto
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentPrecisas de partes de imagem ou de ficheiro (inlineData)
Gemini Native com streamingPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentFormato nativo com server-sent events

Todos os pedidos enviam Authorization: Bearer $POYO_API_KEY. O gemini-4-carbon não suporta /v1/responses nem /v1/messages no PoYo.

Primeiro pedido à Gemini 4 Carbon API com cURL

curl https://api.poyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [
      {"role": "system", "content": "You are a code reviewer. Be specific and cite line numbers."},
      {"role": "user", "content": "Review this function for race conditions: ..."}
    ],
    "max_tokens": 8192,
    "temperature": 1
  }'

model e messages são obrigatórios. Campos opcionais no esquema do PoYo: temperature (0–2), top_p (0–1; usa este ou temperature, não ambos), max_tokens, stream, stop (até 4 sequências), frequency_penalty e presence_penalty (−2 a 2), e n. O content de cada mensagem é uma string.

A resposta é um objeto chat.completion padrão: o texto em choices[0].message.content, o motivo de paragem em choices[0].finish_reason e as contagens em usage.prompt_tokens, usage.completion_tokens e usage.total_tokens.

Python com o SDK da OpenAI

Aponta o SDK para o PoYo e não mudes mais nada:

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])

resp = client.chat.completions.create(
    model="gemini-4-carbon",
    messages=[
        {"role": "system", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Write a migration plan from Celery 4 to Celery 5."},
    ],
    max_tokens=8192,
)

print(resp.choices[0].message.content)
print(resp.choices[0].finish_reason, resp.usage.prompt_tokens, resp.usage.completion_tokens)

Passar do gemini-4-argon, ou de qualquer outro modelo que suporte Chat Completions no PoYo, é uma alteração de uma linha em model.

Streaming com o SDK da OpenAI

Com stream=True, o PoYo envia eventos chat.completion.chunk e termina com data: [DONE]. O texto chega em choices[0].delta.content e o último chunk traz finish_reason e usage:

stream = client.chat.completions.create(
    model="gemini-4-carbon",
    messages=[{"role": "user", "content": "Explain the CAP theorem with one example per trade-off."}],
    max_tokens=4096,
    stream=True,
)

usage = None
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if getattr(chunk, "usage", None):
        usage = chunk.usage
print("\n", usage)

O formato generateContent nativo do Gemini

O endpoint nativo recebe o modelo no caminho do URL. O corpo usa contents (cada um com role user ou model e um array parts), mais os opcionais generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) e safetySettings:

curl "https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent" \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "List three risks of running database migrations during peak traffic."}]}
    ],
    "generationConfig": {"maxOutputTokens": 2048, "temperature": 0.7}
  }'

A resposta é o objeto GenerateContentResponse da Google, devolvido diretamente. O texto está em candidates[].content.parts[].text e as contagens em usageMetadata. Os modelos com thinking podem acrescentar partes com thought: true ou um thoughtSignature, por isso ignora as partes sem texto:

import os, requests

URL = "https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent"
HEADERS = {"Authorization": f"Bearer {os.environ['POYO_API_KEY']}"}

body = {
    "contents": [{"role": "user", "parts": [{"text": "Summarize the trade-offs of event sourcing."}]}],
    "generationConfig": {"maxOutputTokens": 2048},
}
r = requests.post(URL, headers=HEADERS, json=body, timeout=600)
r.raise_for_status()
data = r.json()

text = "".join(
    p["text"]
    for c in data.get("candidates", [])
    for p in c.get("content", {}).get("parts", [])
    if "text" in p and not p.get("thought")
)
print(text)
print(data["usageMetadata"])

Streaming nativo

Troca o método por :streamGenerateContent. A resposta é text/event-stream: cada linha data: é um GenerateContentResponse parcial, o último evento traz finishReason e o stream termina com data: [DONE]. O parâmetro de query alt=sse é aceite, mas não é obrigatório.

import json

STREAM_URL = "https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent"
usage = {}
with requests.post(STREAM_URL, headers=HEADERS, json=body, stream=True, timeout=600) as r:
    r.raise_for_status()
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        payload = line[len("data: "):]
        if payload == "[DONE]":
            break
        event = json.loads(payload)
        for cand in event.get("candidates", []):
            for part in cand.get("content", {}).get("parts", []):
                if "text" in part and not part.get("thought"):
                    print(part["text"], end="", flush=True)
        usage = event.get("usageMetadata", usage)
print("\n", usage)

Entrada multimodal através da Gemini 4 Carbon API

A Google indica texto, imagem, áudio, vídeo e PDF como tipos de entrada do Gemini 4 Carbon. No PoYo, a entrada de ficheiros passa pelo formato nativo, como uma parte inlineData com um mimeType e data em base64. A documentação do PoYo mostra um exemplo com imagem e recomenda colocar as instruções de texto antes das partes multimédia:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {"text": "Read this architecture diagram and list every service that writes to the database."},
        {"inlineData": {"mimeType": "image/png", "data": "BASE64_IMAGE_DATA"}}
      ]
    }
  ],
  "generationConfig": {"maxOutputTokens": 4096}
}

O esquema Chat Completions do PoYo documenta content como uma string, por isso não envies arrays de imagens ao estilo da OpenAI para /v1/chat/completions. Para PDF, áudio e vídeo, a documentação do PoYo não mostra um exemplo separado; envia primeiro um ficheiro pequeno e verifica a resposta antes de construíres um pipeline em cima disso. A multimédia conta para o prompt: usageMetadata.promptTokensDetails discrimina os tokens do prompt por modalidade.

Definir a saída máxima

FormatoCampoSinal de que a saída foi cortada
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason diferente de STOP

A Google indica 65 536 tokens de saída como limite síncrono predefinido e um contexto de 1 048 576 tokens partilhado entre entrada e saída. A página de preços da Google diz que os tokens de thinking são faturados à tarifa de saída, pelo que a contagem de saída em usage pode ser maior do que o texto visível. Os esquemas publicados do PoYo não têm nenhum campo de nível de thinking; o campo de saída máxima é o controlo de comprimento documentado.

Ler o uso e calcular o custo de um pedido

O PoYo cobra pelo gemini-4-carbon $1.60 por 1M de tokens de entrada, $8.00 por 1M de tokens de saída e $0.08 por 1M de tokens de leitura de cache (1 crédito = $0.005).

FormatoTokens de entradaTokens de saída (incl. thinking)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (resposta mais thoughtsTokenCount)
INPUT_USD, OUTPUT_USD = 1.60, 8.00  # PoYo, per 1M tokens

def carbon_cost_usd(input_tokens: int, output_tokens: int) -> float:
    return (input_tokens * INPUT_USD + output_tokens * OUTPUT_USD) / 1_000_000

def carbon_cost_credits(input_tokens: int, output_tokens: int) -> float:
    return carbon_cost_usd(input_tokens, output_tokens) / 0.005

Exemplo medido (produção da PoYo, 16 de novembro de 2026): um pedido /v1/chat/completions sem streaming a pedir ao gemini-4-carbon para rever uma função Python de 40 linhas devolveu prompt_tokens: 480, completion_tokens: 1094 e total_tokens: 1574 em 6,3 segundos, sem tokens de raciocínio reportados. A PoYo cobrou 1,904 créditos, o mesmo valor que a fórmula dá.

input:     480 × $1.60 / 1,000,000 = $0.000768   (0.1536 credits)
output:  1,094 × $8.00 / 1,000,000 = $0.008752   (1.7504 credits)
total:                               $0.009520   (1.9040 credits)

Isto aplica a tarifa de entrada completa a todos os tokens do prompt. Os tokens de leitura de cache são faturados a $0.08 por 1M, mas os esquemas de resposta do PoYo não documentam nenhum campo de tokens em cache, por isso trata esta fórmula como um limite superior. Os cenários de custo em escala estão em Preços da Gemini 4 Carbon API.

Erros que vale a pena tratar

Os endpoints de LLM do PoYo devolvem códigos de estado HTTP reais:

HTTPCausaO que fazer
400Campo em falta ou inválido; corpo {"code": 400, "error": {"type": "validation_error", ...}}Corrige o pedido; lê error.details
400Formato errado para este modelo; a mensagem lista os URIs suportadosUsa Chat Completions ou Gemini Native
400Erro do Gemini Native, no formato da Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Corrige contents / generationConfig
401Chave de API em falta ou inválidaVerifica o cabeçalho Authorization
402Créditos insuficientesCarrega créditos antes de repetir
404ID de modelo desconhecido (model_not_found)Verifica a grafia: gemini-4-carbon
500 / 502 / 503Erro do servidor ou do upstreamRepete com backoff exponencial

A documentação do PoYo diz que os endpoints de LLM não têm atualmente limite de taxa, mas os códigos de erro gerais do PoYo incluem 429. Trata-o com uma espera e uma nova tentativa. Com o SDK da OpenAI, apanha openai.APIStatusError e ramifica com base em status_code. Consulta os códigos de erro do PoYo para veres os corpos completos.

Lista de verificação antes de pores em produção

  • Mantém a POYO_API_KEY do lado do servidor; nunca a incluas em código de browser ou de aplicações móveis.
  • Define sempre max_tokens ou maxOutputTokens, e regista finish_reason / finishReason para que as respostas truncadas fiquem visíveis.
  • Guarda o bloco de uso de cada resposta junto do ID de pedido que atribuis, para poderes reconciliar os gastos por funcionalidade.
  • Coloca primeiro o contexto longo e estável (ficheiros do repositório, documentos) e no fim a pergunta que muda, o que dá ao caching implícito uma oportunidade de se aplicar.
  • Repete apenas respostas 5xx e 429; um 400 vai falhar outra vez até o corpo mudar.

Para ciclos de agentes, output de ferramentas e padrões de contexto longo, continua com Gemini 4 Carbon API para agentes de programação. Para decidires quando o Argon chega, lê Gemini 4 Carbon API vs Gemini 4 Argon.

Perguntas frequentes

Como chamo a Gemini 4 Carbon API em Python?

Usa o SDK da OpenAI com base_url="https://api.poyo.ai/v1", a tua chave PoYo e model="gemini-4-carbon". Para pedidos nativos, faz POST para /v1beta/models/gemini-4-carbon:generateContent com requests.

A Gemini 4 Carbon API suporta streaming?

Sim. Define "stream": true no Chat Completions, ou chama :streamGenerateContent no formato nativo. Ambos devolvem server-sent events que terminam com data: [DONE].

Como envio uma imagem para a Gemini 4 Carbon API?

Usa o endpoint nativo do Gemini com uma parte inlineData (mimeType mais data em base64) depois da tua parte de texto. O Chat Completions no PoYo aceita apenas conteúdo em string.

Como limito os tokens de saída da Gemini 4 Carbon API?

Define max_tokens (Chat Completions) ou generationConfig.maxOutputTokens (nativo). Os tokens de thinking são faturados como saída, por isso compara a contagem de saída em usage com o texto visível quando escolheres o limite.

Porque é que a Gemini 4 Carbon API devolve 400 em /v1/responses?

O gemini-4-carbon suporta apenas Chat Completions e Gemini Native no PoYo. Os outros formatos devolvem 400 com a lista de URIs suportados.

Share: