
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"
| Formato | Endpoint | Use quando |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Você já usa o SDK da OpenAI, mensagens só de texto |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Você precisa de partes de imagem ou arquivo (inlineData) |
| Streaming do Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Formato 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
| Formato | Campo | Sinal de que a saída foi cortada |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason 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).
| Formato | Tokens de entrada | Tokens de saída (incl. raciocínio) |
|---|---|---|
| Chat Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − 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:
| HTTP | Causa | O que fazer |
|---|---|---|
| 400 | Campo ausente ou inválido; corpo {"code": 400, "error": {"type": "validation_error", ...}} | Corrija a requisição; leia error.details |
| 400 | Formato errado para este modelo; a mensagem lista as URIs suportadas | Use Chat Completions ou Gemini Native |
| 400 | Erro do Gemini Native, no formato do Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | Corrija contents / generationConfig |
| 401 | Chave de API ausente ou inválida | Verifique o header Authorization |
| 402 | Créditos insuficientes | Recarregue antes de tentar de novo |
| 404 | ID de modelo desconhecido (model_not_found) | Verifique a grafia: gemini-4-carbon |
| 500 / 502 / 503 | Erro do servidor ou do upstream | Tente 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_KEYno servidor; nunca a inclua em código de navegador ou de app mobile. - Sempre defina
max_tokensoumaxOutputTokense registrefinish_reason/finishReasonpara 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.