
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"
| Formato | Endpoint | Usa-o quando |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Já usas o SDK da OpenAI, mensagens só de texto |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Precisas de partes de imagem ou de ficheiro (inlineData) |
| Gemini Native com streaming | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Formato 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
| 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 |
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).
| Formato | Tokens de entrada | Tokens de saída (incl. thinking) |
|---|---|---|
| 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): 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:
| HTTP | Causa | O que fazer |
|---|---|---|
| 400 | Campo em falta ou inválido; corpo {"code": 400, "error": {"type": "validation_error", ...}} | Corrige o pedido; lê error.details |
| 400 | Formato errado para este modelo; a mensagem lista os URIs suportados | Usa Chat Completions ou Gemini Native |
| 400 | Erro do Gemini Native, no formato da Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | Corrige contents / generationConfig |
| 401 | Chave de API em falta ou inválida | Verifica o cabeçalho Authorization |
| 402 | Créditos insuficientes | Carrega créditos antes de repetir |
| 404 | ID de modelo desconhecido (model_not_found) | Verifica a grafia: gemini-4-carbon |
| 500 / 502 / 503 | Erro do servidor ou do upstream | Repete 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_KEYdo lado do servidor; nunca a incluas em código de browser ou de aplicações móveis. - Define sempre
max_tokensoumaxOutputTokens, e registafinish_reason/finishReasonpara 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.