how-tos

Gemini 4 Carbon API: guia da primeira requisição em cURL, Python e Gemini Native

Poyo.ai Team
10 min read
Share:

Guia da Gemini 4 Carbon API: primeira requisição em cURL e Python

Este guia da Gemini 4 Carbon API leva você de uma chave de API a uma requisição funcionando em cURL, no SDK da OpenAI para Python e no formato nativo generateContent do Google, sempre com o ID de modelo gemini-4-carbon. Cada exemplo segue o schema de requisição publicado pela PoYo em 16 de novembro de 2026. Você pode testar prompts antes na página do modelo Gemini 4 Carbon.

Ainda não conhece o modelo? Comece pela visão geral da Gemini 4 Carbon API para ver limites e posicionamento.

Antes de começar

Crie uma chave no painel da PoYo e mantenha-a no seu servidor:

export POYO_API_KEY="your-poyo-key"
FormatoEndpointUse quando
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsVocê já usa o SDK da OpenAI, mensagens só de texto
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentVocê precisa de partes de imagem ou arquivo (inlineData)
Streaming do Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentFormato nativo com server-sent events

Toda requisição envia Authorization: Bearer $POYO_API_KEY. Na PoYo, gemini-4-carbon não suporta /v1/responses nem /v1/messages.

Primeira requisição à 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 schema da PoYo: temperature (0–2), top_p (0–1; use este ou temperature, não os dois), 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 da parada 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

Aponte o SDK para a PoYo e não mude 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)

Migrar de gemini-4-argon, ou de qualquer outro modelo que suporte Chat Completions na PoYo, é uma mudança de uma linha em model.

Streaming com o SDK da OpenAI

Com stream=True, a 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 nativo generateContent do Gemini

O endpoint nativo recebe o modelo no caminho da URL. O corpo usa contents (cada um com role user ou model e um array parts), além de generationConfig opcional (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 do Google, retornado diretamente. O texto está em candidates[].content.parts[].text e as contagens em usageMetadata. Modelos com raciocínio podem adicionar partes com thought: true ou um thoughtSignature, então ignore 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

Troque 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 é aceito, 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 pela Gemini 4 Carbon API

O Google lista texto, imagem, áudio, vídeo e PDF como tipos de entrada do Gemini 4 Carbon. Na PoYo, a entrada de arquivos passa pelo formato nativo como uma parte inlineData com um mimeType e data em base64. A documentação da PoYo mostra um exemplo com imagem e recomenda colocar as instruções em texto antes das partes de mí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 schema de Chat Completions da PoYo documenta content como string, então não envie arrays de imagem no estilo da OpenAI para /v1/chat/completions. Para PDF, áudio e vídeo, a documentação da PoYo não mostra um exemplo separado; envie primeiro um arquivo pequeno e confira a resposta antes de construir um pipeline em cima disso. A mídia conta no prompt: usageMetadata.promptTokensDetails detalha os tokens do prompt por modalidade.

Definindo a saída máxima

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

O Google lista 65.536 tokens de saída como limite síncrono padrão e um contexto de 1.048.576 tokens compartilhado entre entrada e saída. A página de preços do Google diz que os tokens de raciocínio são cobrados pela tarifa de saída, então a contagem de saída em usage pode ser maior que o texto visível. Os schemas publicados pela PoYo não têm campo de nível de raciocínio; o campo de saída máxima é o controle de tamanho documentado.

Leia o uso e calcule o custo de uma requisição

A PoYo cobra pelo gemini-4-carbon US$ 1,60 por 1M de tokens de entrada, US$ 8,00 por 1M de tokens de saída e US$ 0,08 por 1M de tokens lidos do cache (1 crédito = US$ 0,005).

FormatoTokens de entradaTokens de saída (incl. raciocínio)
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): uma requisição /v1/chat/completions sem streaming pedindo ao gemini-4-carbon para revisar uma função Python de 40 linhas retornou prompt_tokens: 480, completion_tokens: 1094 e total_tokens: 1574 em 6,3 segundos, sem tokens de raciocínio informados. A PoYo cobrou 1,904 crédito, 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)

Isso cobra todos os tokens do prompt pela tarifa cheia de entrada. Tokens lidos do cache são cobrados a US$ 0,08 por 1M, mas os schemas de resposta da PoYo não documentam um campo de tokens em cache, então trate esta fórmula como um limite superior. Cenários de custo em escala estão em Preço da Gemini 4 Carbon API.

Erros que vale a pena tratar

Os endpoints de LLM na PoYo retornam códigos de status HTTP reais:

HTTPCausaO que fazer
400Campo ausente ou inválido; corpo {"code": 400, "error": {"type": "validation_error", ...}}Corrija a requisição; leia error.details
400Formato errado para este modelo; a mensagem lista as URIs suportadasUse Chat Completions ou Gemini Native
400Erro do Gemini Native, no formato do Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Corrija contents / generationConfig
401Chave de API ausente ou inválidaVerifique o header Authorization
402Créditos insuficientesRecarregue antes de tentar de novo
404ID de modelo desconhecido (model_not_found)Verifique a grafia: gemini-4-carbon
500 / 502 / 503Erro do servidor ou do upstreamTente de novo com backoff exponencial

A documentação da PoYo diz que os endpoints de LLM atualmente não têm rate limit, mas os códigos de erro gerais da PoYo incluem 429. Trate-o esperando e tentando de novo. Com o SDK da OpenAI, capture openai.APIStatusError e ramifique por status_code. Veja os códigos de erro da PoYo para os corpos completos.

Checklist antes de publicar

  • Mantenha POYO_API_KEY no servidor; nunca a inclua em código de navegador ou de app mobile.
  • Sempre defina max_tokens ou maxOutputTokens e registre finish_reason / finishReason para que respostas truncadas fiquem visíveis.
  • Guarde o bloco de uso de cada resposta junto ao ID de requisição que você atribui, para conciliar o gasto por funcionalidade.
  • Coloque o contexto longo e estável (arquivos do repositório, documentos) primeiro e a pergunta que muda por último, o que dá ao cache implícito a chance de ser aplicado.
  • Repita apenas respostas 5xx e 429; um 400 vai falhar de novo até o corpo mudar.

Para loops de agentes, saída de ferramentas e padrões de contexto longo, continue com Gemini 4 Carbon API para agentes de programação. Para decidir quando o Argon basta, leia Gemini 4 Carbon API vs Gemini 4 Argon.

Perguntas frequentes

Como chamo a Gemini 4 Carbon API em Python?

Use o SDK da OpenAI com base_url="https://api.poyo.ai/v1", sua chave da PoYo e model="gemini-4-carbon". Para requisições nativas, faça um POST para /v1beta/models/gemini-4-carbon:generateContent com requests.

A Gemini 4 Carbon API suporta streaming?

Sim. Defina "stream": true no Chat Completions ou chame :streamGenerateContent no formato nativo. Os dois retornam server-sent events que terminam com data: [DONE].

Como envio uma imagem para a Gemini 4 Carbon API?

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

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

Defina max_tokens (Chat Completions) ou generationConfig.maxOutputTokens (nativo). Os tokens de raciocínio são cobrados como saída, então compare a contagem de saída em usage com o texto visível ao escolher o limite.

Por que a Gemini 4 Carbon API retorna 400 em /v1/responses?

Na PoYo, gemini-4-carbon suporta apenas Chat Completions e Gemini Native. Outros formatos retornam 400 com a lista de URIs suportadas.

Share: