
A Gemini 4 Carbon API é a escolha da Google para o seu trabalho de programação mais difícil. A Google construiu-a para depuração com vários passos e programação agêntica de horizonte longo, e diz que gasta mais tokens do que o Argon para explorar, raciocinar e executar ciclos de verificação. Este guia liga o gemini-4-carbon (página do modelo) a um agente de programação através do endpoint compatível com a OpenAI do PoYo. O agente faz streaming do output, consegue ler uma grande fatia do repositório, pára num limite rígido de turnos e de dólares e sabe quando passar o trabalho ao Argon.
Se ainda não enviaste um primeiro pedido, começa pelo guia da Gemini 4 Carbon API.
O que a API oferece a um agente de programação
| Item | Gemini 4 Carbon no 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) |
| Limites de taxa | A documentação do PoYo indica que os endpoints de LLM não têm atualmente limite de taxa |
| Erros | 400 campos inválidos, 401 chave inválida, 402 créditos insuficientes, 404 modelo desconhecido; repete 429 / 500 / 502 / 503 com backoff |
A documentação do Chat Completions documenta estes campos de pedido: 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 penalização. O agente abaixo usa apenas esses.
Tool calling: o que está documentado hoje
O PoYo documenta tools para o Anthropic Messages e para o Responses. Não documenta tools nem declarações de funções 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, 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 teu código executa essa ação e devolve o resultado como a mensagem de utilizador seguinte. Isto funciona com qualquer modelo de chat. Quando o PoYo documentar function calling nativo para o Gemini, podes trocar o parser por tool calls reais e manter o resto do ciclo.
Há também uma vantagem de segurança: o modelo só pode pedir quatro ações que tu próprio escreveste. Não consegue executar um comando de shell arbitrário.
Repositório em contexto longo: 1M de entrada, 64K de saída
Uma janela de 1M de tokens permite-te enviar uma grande parte do repositório no primeiro turno, em vez de ires buscar os ficheiros um a um. A tabela de lançamento da Google dá uma razão para o fazer: o Carbon obtém 96,2% no GraphWalks entre 256K e 1M tokens, contra 84,2% do Argon. Há três limites que moldam o ciclo:
- Cada turno reenvia todo o histórico. O snapshot é faturado outra vez em cada chamada. Um snapshot de 300K tokens ao longo de 12 turnos dá pelo menos 3,6M tokens de entrada, ou seja, $5.76 a $1.60 por 1M antes de qualquer saída.
- A saída está limitada a 64K por resposta. Pede um ficheiro por ação
write_file, e não uma reescrita de todo o repositório numa única resposta. - Mede as contagens de tokens, não as adivinhes. O PoYo não documenta nenhum endpoint de tokenizer. Lê
usage.prompt_tokensda primeira chamada e depois ajustaMAX_SNAPSHOT_CHARSao orçamento de tokens que queres.
Caching. A tabela de preços do PoYo tem uma tarifa de leitura de cache para o Carbon ($0.08 por 1M, contra $1.60 para entrada nova), e a Google cobra a entrada em cache com 95% de desconto. A documentação do PoYo não documenta nenhum parâmetro de pedido para caching nem nenhum campo de uso com tokens em cache para os modelos Gemini. Este ciclo não envia nenhum parâmetro de caching e orçamenta todos os tokens do prompt à tarifa de entrada completa. Manter o prompt de sistema e o snapshot como um prefixo inalterado não custa nada, e a tua fatura mostrará se alguma leitura foi cobrada à tarifa de cache.
O ciclo 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 requer Python 3.9 ou posterior. Corre o agente sobre uma cópia ou um branch do repositório, já que write_file substitui ficheiros.
Como funcionam as proteções de custo
| Proteção | O que impede | De onde vem o número |
|---|---|---|
MAX_TURNS | Ciclos que nunca chamam done | Escolha tua; 12 é um ponto de partida |
BUDGET_USD + verificação do pior caso | Gastar acima do limite na chamada seguinte | usage.prompt_tokens e usage.completion_tokens do último chunk do stream, aos $1.60 / $8.00 do PoYo |
MAX_TOKENS_PER_TURN | Uma resposta descontrolada | max_tokens, no máximo 64,000 para o Carbon |
MAX_RESULT_CHARS | Logs de testes enormes a inflacionar todos os turnos seguintes | Truncagem antes de o resultado entrar no histórico |
usage is None → parar | Gastos silenciosos que não consegues medir | O PoYo documenta usage no último chunk do stream |
402 sem repetição | Tempestades de repetições com o saldo a zero | Códigos de erro do PoYo |
A Google cobra a saída do Carbon incluindo os tokens de thinking, por isso um turno pode faturar mais saída do que o JSON visível. É por isso que o orçamento usa completion_tokens e nunca conta os carateres que recebeste. A estimativa conta toda a entrada como sem cache, por isso é um limite superior do que o PoYo vai faturar. Compara-a com o teu painel nas primeiras execuções.
A verificação do pior caso é conservadora. Com um histórico de 300K tokens, mais um turno custa pelo menos $0.48 de entrada mais até $0.128 de saída com max_tokens de 16K. Com um orçamento de $2.00, o ciclo pára antes da chamada que poderia ultrapassar o limite.
Quando recorrer ao Gemini 4 Argon
O Argon recebe o mesmo pedido e custa o mesmo por token de entrada e de saída. A Google chama-lhe "a escolha ideal para a maioria do trabalho de engenharia de software e de conhecimento", com respostas mais rápidas e menor gasto de tokens por turno. Encaminha para ele com run_agent(task, model=ARGON) quando:
- A tarefa é rotineira. Pequenas correções, alterações num único ficheiro e escrita de testes não precisam dos tokens de verificação extra do Carbon.
- Uma resposta tem de ultrapassar os 64K tokens. O Carbon limita a saída a 64K. O nosso guia do Argon cobre o limite de saída muito maior do Argon.
- Queres uma primeira tentativa barata. Corre primeiro o Argon e escala para o Carbon apenas quando os testes continuarem a falhar. O router em Gemini 4 Carbon API vs Gemini 4 Argon API faz isto.
Reserva o Carbon para encontrar a causa raiz em todo o repositório e para ciclos com muito trabalho no terminal. Na tabela da Google, o Carbon obtém 65,2% no Terminal-Bench 4.0 (AA) contra 57,1% do Argon, e 9,6% no SWE-sweep contra 4,3%. O artigo da Google sobre a disponibilidade sugere também uma divisão: o Carbon para funções de arquitetura, coordenação e auditoria, combinado com modelos mais rápidos e leves para o trabalho em paralelo. Neste ciclo, isso significa uma execução de planeamento com o Carbon que atribui ficheiros a workers com o Argon.
Os orçamentos para ambos os modelos estão no artigo sobre os preços da Gemini 4 Carbon API. Se estiveres a ponderar outros fornecedores para o agente, vê 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 no PoYo?
A documentação atual do PoYo não documenta tools nem declarações de funções para os modelos Gemini no Chat Completions nem 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 só precisa de campos documentados.
Posso usar o SDK Python da OpenAI com a Gemini 4 Carbon API?
Sim. Cria OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") e passa model="gemini-4-carbon" a 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. Define max_tokens como 64 000 ou menos.
Como limito os custos da Gemini 4 Carbon API num ciclo de agente?
Limita os turnos, limita max_tokens por turno, trunca os resultados das ferramentas e pára quando o gasto acumulado mais o pior caso do turno seguinte ultrapassariam o teu orçamento. Calcula o gasto a partir de usage.prompt_tokens × $1.60 e usage.completion_tokens × $8.00 por 1M de tokens no PoYo.
A Gemini 4 Carbon API suporta caching de contexto?
O PoYo indica para o Carbon um preço de leitura de cache de $0.08 por 1M de tokens (16 créditos). A sua documentação não documenta atualmente nenhum parâmetro de pedido para caching nem nenhum campo de uso com tokens em cache para os modelos Gemini, por isso orçamenta os prompts à tarifa de entrada completa e verifica na tua fatura se há cobranças à tarifa de cache.
Quando deve um agente de programação usar o Gemini 4 Argon em vez do Carbon?
Usa o Argon para programação rotineira, para qualquer resposta individual que tenha de ultrapassar os 64K tokens e como primeira tentativa mais barata antes de escalares para o Carbon. Ambos custam $1.60 / $8.00 por 1M de tokens no PoYo, mas a Google diz que o Argon usa menos tokens por turno.