
Die Gemini 4 Carbon API ist Googles Wahl für die schwierigste Coding-Arbeit. Google hat das Modell für mehrstufiges Debugging und agentisches Coding mit langem Horizont gebaut und sagt, dass es mehr Token als Argon verbraucht, um zu erkunden, zu schlussfolgern und Verifikationsschleifen zu durchlaufen. Dieser Leitfaden bindet gemini-4-carbon (Modellseite) über PoYos OpenAI-kompatiblen Endpunkt in einen Coding-Agenten ein. Der Agent streamt seinen Output, kann einen großen Teil des Repositorys lesen, stoppt an einer festen Grenze für Turns und Dollar und weiß, wann er Arbeit an Argon übergeben sollte.
Wenn Sie noch keine erste Anfrage gesendet haben, beginnen Sie mit dem Gemini 4 Carbon API-Leitfaden.
Was die API einem Coding-Agenten bietet
| Punkt | Gemini 4 Carbon auf PoYo |
|---|---|
| Modell-ID | gemini-4-carbon |
| Hier verwendeter Agenten-Endpunkt | POST https://api.poyo.ai/v1/chat/completions (OpenAI SDK, base_url="https://api.poyo.ai/v1") |
| Native Alternative | POST /v1beta/models/gemini-4-carbon:generateContent und :streamGenerateContent |
| Kontextfenster | 1M Token: Text, Bild, Audio, Video, PDF |
| Max. Output pro Antwort | 64K Token |
| Streaming | "stream": true; der letzte Chunk enthält finish_reason und usage |
| Preis | $1.60 Input / $8.00 Output / $0.08 Cache-Read pro 1M Token (320 / 1,600 / 16 Credits) |
| Ratenlimits | Laut PoYos Dokumentation sind LLM-Endpunkte derzeit nicht ratenbegrenzt |
| Fehler | 400 ungültige Felder, 401 ungültiger Schlüssel, 402 nicht genügend Credits, 404 unbekanntes Modell; 429 / 500 / 502 / 503 mit Backoff wiederholen |
Die Chat-Completions-Dokumentation dokumentiert diese Anfragefelder: model, messages (String-content mit den Rollen system, user oder assistant), max_tokens, stream, temperature, top_p, stop, n und die Penalty-Felder. Der Agent unten verwendet nur diese.
Tool Calling: was heute dokumentiert ist
PoYo dokumentiert tools für Anthropic Messages und für Responses. Für Gemini-Modelle dokumentiert es weder tools noch Function Declarations, weder in Chat Completions noch in Gemini Native. Responses ist für gemini-4-carbon nicht verfügbar.
Dieser Agent sendet daher kein tools-Array. Stattdessen nutzt er ein JSON-Aktionsprotokoll im normalen Message-Content. Der System-Prompt listet die erlaubten Aktionen auf, das Modell antwortet pro Turn mit einem JSON-Objekt, und Ihr Code führt diese Aktion aus und schickt das Ergebnis als nächste User-Message zurück. Das funktioniert mit jedem Chat-Modell. Sobald PoYo natives Function Calling für Gemini dokumentiert, können Sie den Parser durch echte Tool Calls ersetzen und den Rest der Schleife behalten.
Es gibt auch einen Sicherheitsvorteil: Das Modell kann nur vier Aktionen anfordern, die Sie selbst geschrieben haben. Es kann keinen beliebigen Shell-Befehl ausführen.
Repo-Input mit langem Kontext: 1M rein, 64K raus
Ein Fenster von 1M Token erlaubt es, im ersten Turn einen großen Teil des Repositorys zu senden, statt Dateien einzeln abzurufen. Googles Launch-Tabelle liefert einen Grund dafür: Carbon erreicht bei GraphWalks mit 256K–1M Token 96,2 %, gegenüber 84,2 % für Argon. Drei Limits prägen die Schleife:
- Jeder Turn sendet den gesamten Verlauf erneut. Der Snapshot wird bei jedem Aufruf erneut abgerechnet. Ein Snapshot mit 300K Token über 12 Turns ergibt mindestens 3,6M Input-Token, also $5.76 bei $1.60 pro 1M, noch vor jedem Output.
- Der Output ist auf 64K pro Antwort begrenzt. Fordern Sie eine Datei pro
write_file-Aktion an, kein Rewrite des ganzen Repositorys in einer Antwort. - Token-Zahlen messen, nicht raten. PoYo dokumentiert keinen Tokenizer-Endpunkt. Lesen Sie
usage.prompt_tokensaus dem ersten Aufruf und stimmen Sie dannMAX_SNAPSHOT_CHARSauf das gewünschte Token-Budget ab.
Caching. PoYos Preistabelle enthält einen Cache-Read-Tarif für Carbon ($0.08 pro 1M gegenüber $1.60 für neuen Input), und Google berechnet gecachten Input mit 95 % Rabatt. PoYos Dokumentation beschreibt für Gemini-Modelle weder einen Caching-Parameter in der Anfrage noch ein Usage-Feld für gecachte Token. Diese Schleife sendet keinen Caching-Parameter und kalkuliert jedes Prompt-Token zum vollen Input-Tarif. System-Prompt und Snapshot als unverändertes Präfix beizubehalten kostet nichts, und Ihre Rechnung zeigt, ob Reads zum Cache-Tarif abgerechnet wurden.
Die begrenzte Agenten-Schleife in 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 erfordert Python 3.9 oder neuer. Lassen Sie den Agenten auf einer Kopie oder einem Branch des Repositorys laufen, da write_file Dateien überschreibt.
So funktioniert der Kostenschutz
| Schutz | Was er verhindert | Woher die Zahl kommt |
|---|---|---|
MAX_TURNS | Schleifen, die nie done aufrufen | Ihre Wahl; 12 ist ein Ausgangspunkt |
BUDGET_USD + Worst-Case-Prüfung | Ausgaben über die Grenze beim nächsten Aufruf | usage.prompt_tokens und usage.completion_tokens aus dem letzten Stream-Chunk, zu PoYos $1.60 / $8.00 |
MAX_TOKENS_PER_TURN | Eine einzelne ausufernde Antwort | max_tokens, höchstens 64,000 für Carbon |
MAX_RESULT_CHARS | Riesige Test-Logs, die jeden späteren Turn aufblähen | Kürzung, bevor das Ergebnis in den Verlauf gelangt |
usage is None → Stopp | Unbemerkte Ausgaben, die Sie nicht messen können | PoYo dokumentiert usage im letzten Stream-Chunk |
402 wird nicht wiederholt | Retry-Stürme bei leerem Guthaben | PoYo-Fehlercodes |
Google berechnet Carbons Output einschließlich Thinking-Token, ein Turn kann also mehr Output abrechnen als das sichtbare JSON. Deshalb verwendet das Budget completion_tokens und zählt nie die empfangenen Zeichen. Die Schätzung zählt jeden Input als ungecacht, sie ist also eine Obergrenze für das, was PoYo abrechnet. Gleichen Sie sie bei den ersten Läufen mit Ihrem Dashboard ab.
Die Worst-Case-Prüfung ist konservativ. Bei einem Verlauf von 300K Token kostet ein weiterer Turn mindestens $0.48 für den Input plus bis zu $0.128 für den Output bei max_tokens von 16K. Bei einem Budget von $2.00 stoppt die Schleife vor dem Aufruf, der die Grenze überschreiten könnte.
Wann Sie auf Gemini 4 Argon ausweichen sollten
Argon nimmt dieselbe Anfrage entgegen und kostet pro Input- und Output-Token gleich viel. Google nennt es „die ideale Wahl für den Großteil der Softwareentwicklung und Wissensarbeit“, mit schnelleren Antworten und geringerem Token-Verbrauch pro Turn. Routen Sie mit run_agent(task, model=ARGON) dorthin, wenn:
- Die Aufgabe Routine ist. Kleine Fixes, Änderungen an einer einzelnen Datei und das Schreiben von Tests brauchen Carbons zusätzliche Verifikations-Token nicht.
- Eine Antwort 64K Token überschreiten muss. Carbon begrenzt den Output auf 64K. Unser Argon-Leitfaden behandelt Argons deutlich höheres Output-Limit.
- Sie einen günstigen ersten Versuch wollen. Lassen Sie zuerst Argon laufen und eskalieren Sie nur dann zu Carbon, wenn die Tests weiterhin fehlschlagen. Der Router in Gemini 4 Carbon API vs. Gemini 4 Argon API macht genau das.
Behalten Sie Carbon für repository-weite Ursachenanalyse und terminallastige Schleifen. In Googles Tabelle erreicht Carbon bei Terminal-Bench 4.0 (AA) 65,2 % gegenüber Argons 57,1 % und bei SWE-sweep 9,6 % gegenüber 4,3 %. Googles Verfügbarkeitsbeitrag schlägt außerdem eine Aufteilung vor: Carbon für Architektur-, Koordinations- und Audit-Rollen, kombiniert mit schnelleren, leichteren Modellen für parallele Arbeit. In dieser Schleife bedeutet das einen Carbon-Planer-Lauf, der Dateien an Argon-Worker verteilt.
Budgets für beide Modelle finden Sie im Beitrag zu den Preisen der Gemini 4 Carbon API. Wenn Sie für den Agenten auch andere Anbieter abwägen, lesen Sie Gemini 4 Carbon API vs. Claude Opus 5.5 API vs. GPT-6 Astra API.
Häufig gestellte Fragen
Unterstützt die Gemini 4 Carbon API auf PoYo Function Calling?
PoYos aktuelle Dokumentation beschreibt für Gemini-Modelle weder tools noch Function Declarations in Chat Completions oder Gemini Native. Tools sind für Anthropic Messages und Responses dokumentiert. Dieser Leitfaden verwendet ein JSON-Aktionsprotokoll im Message-Content, das nur dokumentierte Felder braucht.
Kann ich das OpenAI Python SDK mit der Gemini 4 Carbon API verwenden?
Ja. Erstellen Sie OpenAI(api_key=..., base_url="https://api.poyo.ai/v1") und übergeben Sie model="gemini-4-carbon" an chat.completions.create. Streaming funktioniert mit stream=True, und der letzte Chunk enthält usage.
Wie groß sind maximaler Output und Kontextfenster der Gemini 4 Carbon API?
1M Token Kontext und bis zu 64K Output-Token pro Antwort. Setzen Sie max_tokens auf höchstens 64.000.
Wie begrenze ich die Kosten der Gemini 4 Carbon API in einer Agenten-Schleife?
Begrenzen Sie die Turns, begrenzen Sie max_tokens pro Turn, kürzen Sie Tool-Ergebnisse und stoppen Sie, wenn die bisherigen Ausgaben plus ein Worst-Case-Turn Ihr Budget überschreiten würden. Berechnen Sie die Ausgaben bei PoYo aus usage.prompt_tokens × $1.60 und usage.completion_tokens × $8.00 pro 1M Token.
Unterstützt die Gemini 4 Carbon API Kontext-Caching?
PoYo nennt für Carbon einen Cache-Read-Preis von $0.08 pro 1M Token (16 Credits). Die Dokumentation beschreibt für Gemini-Modelle derzeit weder einen Caching-Parameter in der Anfrage noch ein Usage-Feld für gecachte Token. Kalkulieren Sie Prompts daher zum vollen Input-Tarif und prüfen Sie Ihre Rechnung auf Abrechnungen zum Cache-Tarif.
Wann sollte ein Coding-Agent Gemini 4 Argon statt Carbon verwenden?
Verwenden Sie Argon für Routine-Coding, für jede einzelne Antwort, die 64K Token überschreiten muss, und als günstigeren ersten Versuch, bevor Sie zu Carbon eskalieren. Beide kosten bei PoYo $1.60 / $8.00 pro 1M Token, aber laut Google verbraucht Argon weniger Token pro Turn.