
La Gemini 4 Carbon API est le choix de Google pour ses tâches de code les plus difficiles. Google l’a conçue pour le débogage en plusieurs étapes et le codage agentique à long horizon, et indique qu’elle consomme plus de tokens qu’Argon pour explorer, raisonner et exécuter des boucles de vérification. Ce guide branche gemini-4-carbon (page du modèle) dans un agent de code via l’endpoint compatible OpenAI de PoYo. L’agent diffuse sa sortie en streaming, peut lire une grande partie du dépôt, s’arrête à un plafond strict de tours et de dollars, et sait quand confier le travail à Argon.
Si vous n’avez pas encore envoyé de première requête, commencez par le guide de la Gemini 4 Carbon API.
Ce que l’API apporte à un agent de code
| Élément | Gemini 4 Carbon sur PoYo |
|---|---|
| Identifiant de modèle | gemini-4-carbon |
| Endpoint d’agent utilisé ici | POST https://api.poyo.ai/v1/chat/completions (SDK OpenAI, base_url="https://api.poyo.ai/v1") |
| Alternative native | POST /v1beta/models/gemini-4-carbon:generateContent et :streamGenerateContent |
| Fenêtre de contexte | 1M tokens : texte, image, audio, vidéo, PDF |
| Sortie max par réponse | 64K tokens |
| Streaming | "stream": true ; le dernier chunk contient finish_reason et usage |
| Prix | $1.60 en entrée / $8.00 en sortie / $0.08 en lecture de cache par 1M tokens (320 / 1,600 / 16 crédits) |
| Limites de débit | La documentation de PoYo indique que les endpoints LLM ne sont pas soumis à des limites de débit actuellement |
| Erreurs | 400 champs invalides, 401 clé incorrecte, 402 crédits insuffisants, 404 modèle inconnu ; réessayez 429 / 500 / 502 / 503 avec backoff |
La documentation Chat Completions décrit ces champs de requête : model, messages (content sous forme de chaîne avec les rôles system, user ou assistant), max_tokens, stream, temperature, top_p, stop, n et les champs de pénalité. L’agent ci-dessous n’utilise que ceux-là.
Appel d’outils : ce qui est documenté aujourd’hui
PoYo documente tools pour Anthropic Messages et pour Responses. Il ne documente ni tools ni les déclarations de fonctions pour les modèles Gemini, que ce soit dans Chat Completions ou dans Gemini Native. Responses n’est pas disponible pour gemini-4-carbon.
Cet agent n’envoie donc pas de tableau tools. Il utilise à la place un protocole d’actions JSON dans le contenu des messages. Le prompt système liste les actions autorisées, le modèle répond par un objet JSON par tour, et votre code exécute cette action puis renvoie le résultat comme message utilisateur suivant. Cela fonctionne avec n’importe quel modèle de chat. Quand PoYo documentera l’appel de fonctions natif pour Gemini, vous pourrez remplacer le parseur par de vrais appels d’outils et conserver le reste de la boucle.
Il y a aussi un avantage en matière de sécurité : le modèle ne peut demander que quatre actions que vous avez écrites vous-même. Il ne peut pas exécuter une commande shell arbitraire.
Un dépôt en entrée à long contexte : 1M en entrée, 64K en sortie
Une fenêtre de 1M tokens vous permet d’envoyer une grande partie du dépôt dès le premier tour au lieu de récupérer les fichiers un par un. Le tableau de lancement de Google donne une raison de s’en servir : Carbon obtient 96,2 % sur GraphWalks entre 256K et 1M tokens, contre 84,2 % pour Argon. Trois limites façonnent la boucle :
- Chaque tour renvoie tout l’historique. L’instantané est refacturé à chaque appel. Un instantané de 300K tokens sur 12 tours représente au moins 3,6M tokens en entrée, soit 5,76 $ à 1,60 $ par million, avant toute sortie.
- La sortie est plafonnée à 64K par réponse. Demandez un fichier par action
write_file, pas une réécriture de tout le dépôt en une seule réponse. - Mesurez les décomptes de tokens au lieu de les deviner. PoYo ne documente aucun endpoint de tokenizer. Lisez
usage.prompt_tokensdès le premier appel, puis ajustezMAX_SNAPSHOT_CHARSau budget de tokens souhaité.
Mise en cache. La grille tarifaire de PoYo comporte un tarif de lecture de cache pour Carbon (0,08 $ par million, contre 1,60 $ pour une entrée nouvelle), et Google facture l’entrée en cache à -95 %. La documentation de PoYo ne décrit ni paramètre de requête de mise en cache ni champ d’usage pour les tokens en cache pour les modèles Gemini. Cette boucle n’envoie aucun paramètre de mise en cache et budgète chaque token du prompt au plein tarif d’entrée. Garder le prompt système et l’instantané comme préfixe inchangé ne coûte rien, et votre facture montrera si des lectures ont été facturées au tarif du cache.
La boucle d’agent bornée en 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 nécessite Python 3.9 ou une version ultérieure. Exécutez l’agent sur une copie ou une branche du dépôt, puisque write_file écrase les fichiers.
Fonctionnement des garde-fous de coût
| Garde-fou | Ce qu’il empêche | D’où vient le chiffre |
|---|---|---|
MAX_TURNS | Les boucles qui n’appellent jamais done | À vous de choisir ; 12 est un point de départ |
BUDGET_USD + vérification du pire cas | Dépasser le plafond lors du prochain appel | usage.prompt_tokens et usage.completion_tokens du dernier chunk du flux, aux tarifs PoYo de $1.60 / $8.00 |
MAX_TOKENS_PER_TURN | Une réponse qui s’emballe | max_tokens, au plus 64,000 pour Carbon |
MAX_RESULT_CHARS | D’énormes journaux de tests qui gonflent chaque tour suivant | Troncature avant que le résultat n’entre dans l’historique |
usage is None → arrêt | Des dépenses silencieuses impossibles à mesurer | PoYo documente usage sur le dernier chunk du flux |
402 non réessayé | Des rafales de tentatives sur un solde vide | Codes d’erreur PoYo |
Google facture la sortie de Carbon tokens de réflexion inclus : un tour peut donc facturer plus de sortie que le JSON visible. C’est pourquoi le budget utilise completion_tokens et ne compte jamais les caractères reçus. L’estimation compte toute l’entrée comme hors cache : c’est donc une borne supérieure de ce que PoYo facturera. Comparez-la à votre tableau de bord lors des premières exécutions.
La vérification du pire cas est prudente. Avec un historique de 300K tokens, un tour de plus coûte au moins 0,48 $ en entrée plus jusqu’à 0,128 $ en sortie avec un max_tokens de 16K. Avec un budget de 2,00 $, la boucle s’arrête avant l’appel qui pourrait dépasser le plafond.
Quand se replier sur Gemini 4 Argon
Argon accepte la même requête et coûte la même chose par token d’entrée et de sortie. Google le qualifie de « choix idéal pour la majorité des tâches d’ingénierie logicielle et de travail intellectuel », avec des réponses plus rapides et moins de tokens consommés par tour. Routez vers lui avec run_agent(task, model=ARGON) lorsque :
- La tâche est courante. Les petits correctifs, les modifications d’un seul fichier et l’écriture de tests n’ont pas besoin des tokens de vérification supplémentaires de Carbon.
- Une réponse doit dépasser 64K tokens. Carbon plafonne la sortie à 64K. Notre guide Argon détaille la limite de sortie bien plus élevée d’Argon.
- Vous voulez une première tentative peu coûteuse. Lancez d’abord Argon et n’escaladez vers Carbon que si les tests échouent encore. C’est ce que fait le routeur de Gemini 4 Carbon API vs Gemini 4 Argon API.
Réservez Carbon à la recherche de cause racine à l’échelle du dépôt et aux boucles à forte composante terminal. Dans le tableau de Google, Carbon obtient 65,2 % sur Terminal-Bench 4.0 (AA) contre 57,1 % pour Argon, et 9,6 % sur SWE-sweep contre 4,3 %. L’article de Google sur la disponibilité suggère aussi une répartition : Carbon pour les rôles d’architecture, de coordination et d’audit, associé à des modèles plus rapides et plus légers pour le travail en parallèle. Dans cette boucle, cela signifie une exécution de planification sur Carbon qui attribue des fichiers à des workers Argon.
Les budgets des deux modèles figurent dans l’article sur les prix de la Gemini 4 Carbon API. Si vous envisagez d’autres éditeurs pour l’agent, voir Gemini 4 Carbon API vs Claude Opus 5.5 API vs GPT-6 Astra API.
Questions fréquentes
La Gemini 4 Carbon API prend-elle en charge l’appel de fonctions sur PoYo ?
La documentation actuelle de PoYo ne décrit ni tools ni les déclarations de fonctions pour les modèles Gemini dans Chat Completions ou Gemini Native. Les outils sont documentés pour Anthropic Messages et Responses. Ce guide utilise un protocole d’actions JSON dans le contenu des messages, qui ne nécessite que des champs documentés.
Puis-je utiliser le SDK Python d’OpenAI avec la Gemini 4 Carbon API ?
Oui. Créez OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") et passez model="gemini-4-carbon" à chat.completions.create. Le streaming fonctionne avec stream=True, et le dernier chunk contient usage.
Quelles sont la sortie maximale et la fenêtre de contexte de la Gemini 4 Carbon API ?
1M tokens de contexte et jusqu’à 64K tokens de sortie par réponse. Réglez max_tokens sur 64 000 ou moins.
Comment limiter les coûts de la Gemini 4 Carbon API dans une boucle d’agent ?
Plafonnez les tours, plafonnez max_tokens par tour, tronquez les résultats des outils, et arrêtez-vous quand les dépenses cumulées plus un prochain tour dans le pire cas dépasseraient votre budget. Calculez les dépenses à partir de usage.prompt_tokens × 1,60 $ et usage.completion_tokens × 8,00 $ par million de tokens sur PoYo.
La Gemini 4 Carbon API prend-elle en charge la mise en cache du contexte ?
PoYo indique pour Carbon un prix de lecture de cache de 0,08 $ par million de tokens (16 crédits). Sa documentation ne décrit actuellement ni paramètre de requête de mise en cache ni champ d’usage pour les tokens en cache pour les modèles Gemini : budgétez donc les prompts au plein tarif d’entrée et vérifiez votre facture pour repérer des montants au tarif du cache.
Quand un agent de code doit-il utiliser Gemini 4 Argon plutôt que Carbon ?
Utilisez Argon pour le code courant, pour toute réponse unique qui doit dépasser 64K tokens, et comme première tentative moins chère avant d’escalader vers Carbon. Les deux coûtent 1,60 $ / 8,00 $ par million de tokens sur PoYo, mais Google indique qu’Argon utilise moins de tokens par tour.