
Dieser Leitfaden zur Gemini 4 Carbon API führt Sie vom API-Schlüssel zu einer funktionierenden Anfrage mit cURL, dem Python OpenAI SDK und Googles nativem generateContent-Format, jeweils mit der Modell-ID gemini-4-carbon. Jedes Beispiel folgt PoYos veröffentlichtem Anfrageschema, Stand 16. November 2026. Prompts können Sie zuerst auf der Gemini 4 Carbon Modellseite testen.
Neu bei diesem Modell? Beginnen Sie mit dem Überblick zur Gemini 4 Carbon API, dort finden Sie Limits und Einordnung.
Bevor Sie beginnen
Erstellen Sie im PoYo-Dashboard einen Schlüssel und bewahren Sie ihn auf Ihrem Server auf:
export POYO_API_KEY="your-poyo-key"
| Format | Endpunkt | Verwenden, wenn |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Sie bereits das OpenAI SDK nutzen und reine Text-Messages senden |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Sie Bild- oder Datei-Parts (inlineData) brauchen |
| Gemini Native Streaming | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Natives Format mit Server-Sent Events |
Jede Anfrage sendet Authorization: Bearer $POYO_API_KEY. gemini-4-carbon unterstützt auf PoYo weder /v1/responses noch /v1/messages.
Erste Anfrage an die Gemini 4 Carbon API mit 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 und messages sind Pflichtfelder. Optionale Felder in PoYos Schema: temperature (0–2), top_p (0–1; verwenden Sie entweder dieses oder temperature, nicht beide), max_tokens, stream, stop (bis zu 4 Sequenzen), frequency_penalty und presence_penalty (−2 bis 2) sowie n. Das content jeder Message ist ein String.
Die Antwort ist ein Standard-Objekt vom Typ chat.completion: der Text in choices[0].message.content, der Abbruchgrund in choices[0].finish_reason und die Zählwerte in usage.prompt_tokens, usage.completion_tokens und usage.total_tokens.
Python mit dem OpenAI SDK
Richten Sie das SDK auf PoYo aus und ändern Sie sonst nichts:
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)
Der Wechsel von gemini-4-argon oder einem anderen Modell, das auf PoYo Chat Completions unterstützt, ist eine einzeilige Änderung an model.
Streaming mit dem OpenAI SDK
Mit stream=True sendet PoYo chat.completion.chunk-Events und schließt mit data: [DONE] ab. Der Text kommt in choices[0].delta.content, und der letzte Chunk enthält finish_reason und 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)
Das native generateContent-Format von Gemini
Beim nativen Endpunkt steht das Modell im URL-Pfad. Der Body verwendet contents (jeweils mit role user oder model und einem parts-Array), dazu optional generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) und 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}
}'
Die Antwort ist Googles GenerateContentResponse-Objekt, das direkt zurückgegeben wird. Der Text steht in candidates[].content.parts[].text, die Zählwerte in usageMetadata. Thinking-Modelle können Parts mit thought: true oder einer thoughtSignature hinzufügen, überspringen Sie also Parts ohne Text:
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"])
Natives Streaming
Tauschen Sie die Methode gegen :streamGenerateContent. Die Antwort ist text/event-stream: Jede data:-Zeile ist eine partielle GenerateContentResponse, das letzte Event enthält finishReason, und der Stream endet mit data: [DONE]. Der Query-Parameter alt=sse wird akzeptiert, ist aber nicht erforderlich.
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)
Multimodaler Input über die Gemini 4 Carbon API
Google nennt Text, Bild, Audio, Video und PDF als Input-Typen für Gemini 4 Carbon. Auf PoYo läuft Datei-Input über das native Format als inlineData-Part mit einem mimeType und base64-kodierten data. PoYos Dokumentation zeigt ein Bildbeispiel und empfiehlt, Textanweisungen vor die Medien-Parts zu setzen:
{
"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}
}
PoYos Chat-Completions-Schema dokumentiert content als String, senden Sie also keine Bild-Arrays im OpenAI-Stil an /v1/chat/completions. Für PDF, Audio und Video zeigt PoYos Dokumentation kein eigenes Beispiel; senden Sie zuerst eine kleine Datei und prüfen Sie die Antwort, bevor Sie eine Pipeline darauf aufbauen. Medien zählen zum Prompt: usageMetadata.promptTokensDetails schlüsselt die Prompt-Token nach Modalität auf.
Den maximalen Output festlegen
| Format | Feld | Signal, dass der Output abgeschnitten wurde |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason ungleich STOP |
Google nennt 65.536 Output-Token als synchrone Standardobergrenze und einen Kontext von 1.048.576 Token, den sich Input und Output teilen. Laut Googles Preisseite werden Thinking-Token zum Output-Tarif abgerechnet, daher kann der Output-Wert in usage größer sein als der sichtbare Text. PoYos veröffentlichte Schemas haben kein Feld für das Thinking Level; das Feld für den maximalen Output ist die dokumentierte Längensteuerung.
Usage auslesen und die Kosten einer Anfrage berechnen
PoYo berechnet für gemini-4-carbon $1.60 pro 1M Input-Token, $8.00 pro 1M Output-Token und $0.08 pro 1M Cache-Read-Token (1 Credit = $0.005).
| Format | Input-Token | Output-Token (inkl. Thinking) |
|---|---|---|
| Chat Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − promptTokenCount (Antwort plus 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
Gemessenes Beispiel (PoYo-Produktion, 16. November 2026): Eine nicht streamende /v1/chat/completions-Anfrage, in der gemini-4-carbon eine 40-zeilige Python-Funktion prüfen sollte, lieferte prompt_tokens: 480, completion_tokens: 1094 und total_tokens: 1574 in 6,3 Sekunden, ohne gemeldete Thinking-Tokens. PoYo hat dafür 1,904 Credits abgerechnet, denselben Wert, den die Formel ergibt.
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)
Hier wird jedes Prompt-Token zum vollen Input-Tarif berechnet. Cache-Read-Token kosten $0.08 pro 1M, aber PoYos Antwortschemas dokumentieren kein Feld für gecachte Token, betrachten Sie diese Formel also als Obergrenze. Kostenszenarien im großen Maßstab finden Sie unter Gemini 4 Carbon API Preise.
Fehler, die Sie behandeln sollten
LLM-Endpunkte auf PoYo geben echte HTTP-Statuscodes zurück:
| HTTP | Ursache | Was zu tun ist |
|---|---|---|
| 400 | Fehlendes oder ungültiges Feld; Body {"code": 400, "error": {"type": "validation_error", ...}} | Anfrage korrigieren; error.details lesen |
| 400 | Falsches Format für dieses Modell; die Meldung listet die unterstützten URIs | Chat Completions oder Gemini Native verwenden |
| 400 | Gemini-Native-Fehler in Googles Form {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | contents / generationConfig korrigieren |
| 401 | Fehlender oder ungültiger API-Schlüssel | Authorization-Header prüfen |
| 402 | Nicht genügend Credits | Vor dem erneuten Versuch aufladen |
| 404 | Unbekannte Modell-ID (model_not_found) | Schreibweise prüfen: gemini-4-carbon |
| 500 / 502 / 503 | Server- oder Upstream-Fehler | Mit exponentiellem Backoff wiederholen |
Laut PoYos Dokumentation sind LLM-Endpunkte derzeit nicht ratenbegrenzt, PoYos allgemeine Fehlercodes enthalten aber 429. Behandeln Sie ihn mit Warten und erneutem Versuch. Mit dem OpenAI SDK fangen Sie openai.APIStatusError ab und verzweigen nach status_code. Die vollständigen Bodies finden Sie in den PoYo-Fehlercodes.
Checkliste vor dem Release
- Halten Sie
POYO_API_KEYauf dem Server; liefern Sie ihn nie in Browser- oder Mobile-Code aus. - Setzen Sie immer
max_tokensodermaxOutputTokensund loggen Siefinish_reason/finishReason, damit abgeschnittene Antworten sichtbar werden. - Speichern Sie den Usage-Block jeder Antwort neben der Anfrage-ID, die Sie vergeben, damit Sie die Ausgaben pro Feature abgleichen können.
- Stellen Sie langen, stabilen Kontext (Repository-Dateien, Dokumente) an den Anfang und die wechselnde Frage ans Ende; so hat implizites Caching eine Chance zu greifen.
- Wiederholen Sie nur 5xx- und
429-Antworten; ein 400 schlägt erneut fehl, bis sich der Body ändert.
Für Agenten-Schleifen, Tool-Output und Muster mit langem Kontext lesen Sie weiter unter Gemini 4 Carbon API für Coding-Agenten. Um zu entscheiden, wann Argon ausreicht, lesen Sie Gemini 4 Carbon API vs. Gemini 4 Argon.
Häufig gestellte Fragen
Wie rufe ich die Gemini 4 Carbon API in Python auf?
Verwenden Sie das OpenAI SDK mit base_url="https://api.poyo.ai/v1", Ihrem PoYo-Schlüssel und model="gemini-4-carbon". Für native Anfragen senden Sie mit requests einen POST an /v1beta/models/gemini-4-carbon:generateContent.
Unterstützt die Gemini 4 Carbon API Streaming?
Ja. Setzen Sie bei Chat Completions "stream": true oder rufen Sie im nativen Format :streamGenerateContent auf. Beide liefern Server-Sent Events, die mit data: [DONE] enden.
Wie sende ich ein Bild an die Gemini 4 Carbon API?
Verwenden Sie den nativen Gemini-Endpunkt mit einem inlineData-Part (mimeType plus base64-kodierte data) nach Ihrem Text-Part. Chat Completions akzeptiert auf PoYo nur String-Content.
Wie begrenze ich die Output-Token der Gemini 4 Carbon API?
Setzen Sie max_tokens (Chat Completions) oder generationConfig.maxOutputTokens (nativ). Thinking-Token werden als Output abgerechnet, vergleichen Sie also beim Festlegen der Obergrenze den Output-Wert in usage mit dem sichtbaren Text.
Warum gibt die Gemini 4 Carbon API bei /v1/responses einen 400 zurück?
gemini-4-carbon unterstützt auf PoYo nur Chat Completions und Gemini Native. Andere Formate liefern 400 mit der Liste der unterstützten URIs.