
A Gemini 4 Carbon API é a escolha do Google para o seu trabalho de programação mais difícil. O Google a criou para depuração de várias etapas e programação agêntica de longo horizonte, e diz que ela gasta mais tokens que o Argon para explorar, raciocinar e executar loops de verificação. Este guia conecta o gemini-4-carbon (página do modelo) a um agente de programação pelo endpoint compatível com a OpenAI da PoYo. O agente faz streaming da saída, consegue ler uma grande parte do repositório, para em um limite rígido de turnos e de dólares e sabe quando passar o trabalho para o Argon.
Se você ainda não enviou uma primeira requisição, comece pelo guia da Gemini 4 Carbon API.
O que a API oferece a um agente de programação
| Item | Gemini 4 Carbon na PoYo |
|---|---|
| ID do modelo | gemini-4-carbon |
| Endpoint do agente usado aqui | POST https://api.poyo.ai/v1/chat/completions (SDK da OpenAI, base_url="https://api.poyo.ai/v1") |
| Alternativa nativa | POST /v1beta/models/gemini-4-carbon:generateContent e :streamGenerateContent |
| Janela de contexto | 1M tokens: texto, imagem, áudio, vídeo, PDF |
| Saída máxima por resposta | 64K tokens |
| Streaming | "stream": true; o último chunk traz finish_reason e usage |
| Preço | $1.60 de entrada / $8.00 de saída / $0.08 de leitura de cache por 1M de tokens (320 / 1,600 / 16 créditos) |
| Rate limits | A documentação da PoYo diz que os endpoints de LLM atualmente não têm rate limit |
| Erros | 400 campos inválidos, 401 chave inválida, 402 créditos insuficientes, 404 modelo desconhecido; repita 429 / 500 / 502 / 503 com backoff |
A documentação do Chat Completions documenta estes campos de requisição: model, messages (content em string com os papéis system, user ou assistant), max_tokens, stream, temperature, top_p, stop, n e os campos de penalidade. O agente abaixo usa apenas esses.
Chamada de ferramentas: o que está documentado hoje
A PoYo documenta tools para o Anthropic Messages e para o Responses. Ela não documenta tools nem declarações de função para os modelos Gemini, nem no Chat Completions nem no Gemini Native. O Responses não está disponível para o gemini-4-carbon.
Por isso, este agente não envia um array tools. Em vez disso, ele usa um protocolo de ações em JSON no conteúdo simples das mensagens. O prompt de sistema lista as ações permitidas, o modelo responde com um objeto JSON por turno e o seu código executa essa ação e devolve o resultado como a próxima mensagem do usuário. Isso funciona com qualquer modelo de chat. Quando a PoYo documentar function calling nativo para o Gemini, você pode trocar o parser por chamadas de ferramenta reais e manter o resto do loop.
Há também um benefício de segurança: o modelo só pode solicitar quatro ações que você mesmo escreveu. Ele não consegue executar um comando de shell arbitrário.
Entrada de repositório com contexto longo: 1M de entrada, 64K de saída
Uma janela de 1M de tokens permite enviar uma grande parte do repositório no primeiro turno, em vez de buscar os arquivos um a um. A tabela de lançamento do Google dá um motivo para isso: o Carbon marca 96,2% no GraphWalks com 256K–1M tokens, contra 84,2% do Argon. Três limites moldam o loop:
- Todo turno reenvia o histórico inteiro. O snapshot é cobrado de novo em cada chamada. Um snapshot de 300K tokens ao longo de 12 turnos dá pelo menos 3,6M de tokens de entrada, o que equivale a US$ 5,76 a US$ 1,60 por 1M, antes de qualquer saída.
- A saída é limitada a 64K por resposta. Peça um arquivo por ação
write_file, não uma reescrita do repositório inteiro em uma única resposta. - Meça as contagens de tokens em vez de adivinhar. A PoYo não documenta um endpoint de tokenizer. Leia
usage.prompt_tokensna primeira chamada e depois ajusteMAX_SNAPSHOT_CHARSao orçamento de tokens que você quer.
Cache. A tabela de preços da PoYo tem uma tarifa de leitura de cache para o Carbon (US$ 0,08 por 1M, contra US$ 1,60 para entrada nova), e o Google cobra a entrada em cache com 95% de desconto. A documentação da PoYo não documenta um parâmetro de requisição para cache nem um campo de uso com tokens em cache para os modelos Gemini. Este loop não envia nenhum parâmetro de cache e orça todo token do prompt pela tarifa cheia de entrada. Manter o prompt de sistema e o snapshot como um prefixo inalterado não custa nada, e a sua fatura vai mostrar se alguma leitura foi cobrada pela tarifa de cache.
O loop de agente limitado em Python
import json
import os
import subprocess
import time
from pathlib import Path
from openai import OpenAI, APIStatusError
client = OpenAI(api_key=os.environ["POYO_API_KEY"], base_url="https://api.poyo.ai/v1")
CARBON, ARGON = "gemini-4-carbon", "gemini-4-argon"
PRICE_IN, PRICE_OUT = 1.60, 8.00 # PoYo USD per 1M tokens, same for both (2026-11-16)
MAX_TURNS = 12
BUDGET_USD = 2.00
MAX_TOKENS_PER_TURN = 16_000 # Carbon allows up to 64,000
MAX_SNAPSHOT_CHARS = 400_000 # tune against usage.prompt_tokens
MAX_RESULT_CHARS = 20_000
REPO = Path("./my-repo").resolve()
SYSTEM = """You are a coding agent working in a Python repository.
Reply with exactly one JSON object and nothing else. Allowed actions:
{"action": "read_file", "path": "<relative path>"}
{"action": "write_file", "path": "<relative path>", "content": "<full file content>"}
{"action": "run_tests"}
{"action": "done", "summary": "<what changed and why>"}"""
def snapshot() -> str:
parts, total = [], 0
for p in sorted(REPO.rglob("*.py")):
block = f"### {p.relative_to(REPO)}\n{p.read_text(encoding='utf-8', errors='replace')}\n"
if total + len(block) > MAX_SNAPSHOT_CHARS:
break
parts.append(block)
total += len(block)
return "".join(parts)
def safe_path(rel: str) -> Path:
p = (REPO / rel).resolve()
if not p.is_relative_to(REPO):
raise ValueError("path outside repository")
return p
def execute(action: dict) -> str:
kind = action.get("action")
if kind == "read_file":
return safe_path(action["path"]).read_text(encoding="utf-8", errors="replace")
if kind == "write_file":
safe_path(action["path"]).write_text(action["content"], encoding="utf-8")
return "written"
if kind == "run_tests":
r = subprocess.run(["pytest", "-q"], cwd=REPO, capture_output=True, text=True, timeout=600)
return f"exit={r.returncode}\n{r.stdout}\n{r.stderr}"
raise ValueError(f"unknown action {kind!r}")
def call(model: str, messages: list):
"""One streamed turn. Returns (text, usage, finish_reason)."""
for attempt in range(4):
try:
stream = client.chat.completions.create(
model=model, messages=messages, max_tokens=MAX_TOKENS_PER_TURN, stream=True
)
text, usage, finish = [], None, None
for chunk in stream:
if chunk.choices:
choice = chunk.choices[0]
if choice.delta and choice.delta.content:
text.append(choice.delta.content)
print(choice.delta.content, end="", flush=True)
finish = choice.finish_reason or finish
if getattr(chunk, "usage", None):
usage = chunk.usage
return "".join(text), usage, finish
except APIStatusError as e:
if e.status_code in (429, 500, 502, 503) and attempt < 3:
time.sleep(2 ** attempt)
continue
raise # 400, 401, 402, 404: fix the request or the account, don't retry
def parse(text: str) -> dict:
t = text.strip()
if t.startswith("```"):
t = t.strip("`").removeprefix("json").strip()
return json.loads(t)
def run_agent(task: str, model: str = CARBON) -> dict:
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": f"Repository snapshot:\n{snapshot()}\n\nTask: {task}"},
]
spent, last_prompt = 0.0, 0
for turn in range(1, MAX_TURNS + 1):
# Worst case for the next turn: at least last turn's input plus a full output
worst_next = last_prompt / 1e6 * PRICE_IN + MAX_TOKENS_PER_TURN / 1e6 * PRICE_OUT
if spent + worst_next > BUDGET_USD:
return {"status": "budget_stop", "turns": turn - 1, "spent_usd": round(spent, 4)}
text, usage, finish = call(model, messages)
if usage is None:
raise RuntimeError("no usage in stream; stopping so the budget stays enforceable")
spent += usage.prompt_tokens / 1e6 * PRICE_IN + usage.completion_tokens / 1e6 * PRICE_OUT
last_prompt = usage.prompt_tokens
messages.append({"role": "assistant", "content": text})
if finish == "length":
messages.append({"role": "user", "content": "Reply was cut off. Send one shorter JSON action."})
continue
try:
action = parse(text)
except json.JSONDecodeError:
messages.append({"role": "user", "content": "Reply with exactly one JSON object."})
continue
if action.get("action") == "done":
return {"status": "done", "summary": action.get("summary"), "turns": turn, "spent_usd": round(spent, 4)}
try:
result = execute(action)
except Exception as e: # report the failure to the model instead of crashing
result = f"error: {e}"
messages.append({"role": "user", "content": f"Result of {action.get('action')}:\n{result[:MAX_RESULT_CHARS]}"})
return {"status": "max_turns", "turns": MAX_TURNS, "spent_usd": round(spent, 4)}
if __name__ == "__main__":
print(run_agent("tests/test_parser.py::test_unicode fails. Find the root cause and fix it."))
Path.is_relative_to exige Python 3.9 ou posterior. Rode o agente em uma cópia ou em um branch do repositório, já que write_file sobrescreve arquivos.
Como funcionam as proteções de custo
| Proteção | O que ela impede | De onde vem o número |
|---|---|---|
MAX_TURNS | Loops que nunca chamam done | Escolha sua; 12 é um ponto de partida |
BUDGET_USD + verificação de pior caso | Gastar além do limite na próxima chamada | usage.prompt_tokens e usage.completion_tokens do último chunk do stream, aos $1.60 / $8.00 da PoYo |
MAX_TOKENS_PER_TURN | Uma resposta descontrolada | max_tokens, no máximo 64,000 para o Carbon |
MAX_RESULT_CHARS | Logs de teste enormes inflando todos os turnos seguintes | Truncamento antes de o resultado entrar no histórico |
usage is None → parar | Gasto silencioso que você não consegue medir | A PoYo documenta usage no último chunk do stream |
402 sem nova tentativa | Tempestades de retentativas com saldo zerado | Códigos de erro da PoYo |
O Google cobra a saída do Carbon incluindo os tokens de raciocínio, então um turno pode cobrar mais saída do que o JSON visível. Por isso o orçamento usa completion_tokens e nunca conta os caracteres recebidos. A estimativa conta toda a entrada como sem cache, então é um limite superior do que a PoYo vai cobrar. Compare-a com o seu painel nas primeiras execuções.
A verificação de pior caso é conservadora. Com um histórico de 300K tokens, mais um turno custa pelo menos US$ 0,48 de entrada mais até US$ 0,128 de saída com max_tokens de 16K. Com um orçamento de US$ 2,00, o loop para antes da chamada que poderia ultrapassar o limite.
Quando recorrer ao Gemini 4 Argon
O Argon recebe a mesma requisição e custa o mesmo por token de entrada e de saída. O Google o chama de "a escolha ideal para a maior parte da engenharia de software e do trabalho com conhecimento", com respostas mais rápidas e menor gasto de tokens por turno. Encaminhe para ele com run_agent(task, model=ARGON) quando:
- A tarefa for rotineira. Correções pequenas, mudanças em um único arquivo e escrita de testes não precisam dos tokens extras de verificação do Carbon.
- Uma resposta precisar passar de 64K tokens. O Carbon limita a saída a 64K. Nosso guia do Argon cobre o limite de saída bem maior do Argon.
- Você quiser uma primeira tentativa barata. Rode o Argon primeiro e escale para o Carbon só quando os testes ainda falharem. O roteador em Gemini 4 Carbon API vs Gemini 4 Argon API faz isso.
Reserve o Carbon para encontrar causas raiz em todo o repositório e para loops pesados no terminal. Na tabela do Google, o Carbon marca 65,2% no Terminal-Bench 4.0 (AA) contra 57,1% do Argon, e 9,6% no SWE-sweep contra 4,3%. O post de disponibilidade do Google também sugere uma divisão: o Carbon para papéis de arquitetura, coordenação e auditoria, combinado com modelos mais rápidos e leves para o trabalho em paralelo. Neste loop, isso significa uma execução do Carbon como planejador que distribui arquivos para workers do Argon.
Os orçamentos para os dois modelos estão no post de preços da Gemini 4 Carbon API. Se você está avaliando outros fornecedores para o agente, veja Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.
Perguntas frequentes
A Gemini 4 Carbon API suporta function calling na PoYo?
A documentação atual da PoYo não documenta tools nem declarações de função para os modelos Gemini no Chat Completions ou no Gemini Native. As ferramentas estão documentadas para o Anthropic Messages e o Responses. Este guia usa um protocolo de ações em JSON no conteúdo das mensagens, que precisa apenas de campos documentados.
Posso usar o SDK da OpenAI para Python com a Gemini 4 Carbon API?
Sim. Crie OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") e passe model="gemini-4-carbon" para chat.completions.create. O streaming funciona com stream=True, e o último chunk traz usage.
Qual é a saída máxima e a janela de contexto da Gemini 4 Carbon API?
1M de tokens de contexto e até 64K tokens de saída por resposta. Defina max_tokens como 64.000 ou menos.
Como limito os custos da Gemini 4 Carbon API em um loop de agente?
Limite os turnos, limite max_tokens por turno, trunque os resultados das ferramentas e pare quando o gasto até agora mais um próximo turno no pior caso ultrapassaria o seu orçamento. Calcule o gasto com usage.prompt_tokens × US$ 1,60 e usage.completion_tokens × US$ 8,00 por 1M de tokens na PoYo.
A Gemini 4 Carbon API suporta cache de contexto?
A PoYo lista um preço de leitura de cache para o Carbon de US$ 0,08 por 1M de tokens (16 créditos). A documentação atualmente não documenta um parâmetro de requisição para cache nem um campo de uso com tokens em cache para os modelos Gemini, então orce os prompts pela tarifa cheia de entrada e verifique na sua fatura se há cobranças pela tarifa de cache.
Quando um agente de programação deve usar o Gemini 4 Argon em vez do Carbon?
Use o Argon para programação rotineira, para qualquer resposta única que precise passar de 64K tokens e como uma primeira tentativa mais barata antes de escalar para o Carbon. Os dois custam US$ 1,60 / US$ 8,00 por 1M de tokens na PoYo, mas o Google diz que o Argon usa menos tokens por turno.