how-tos

Gemini 4 Carbon API-Leitfaden: Erste Anfrage mit cURL, Python und Gemini Native

Poyo.ai Team
9 min read
Share:

Gemini 4 Carbon API-Leitfaden: erste Anfrage mit cURL und Python

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"
FormatEndpunktVerwenden, wenn
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsSie bereits das OpenAI SDK nutzen und reine Text-Messages senden
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentSie Bild- oder Datei-Parts (inlineData) brauchen
Gemini Native StreamingPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentNatives 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

FormatFeldSignal, dass der Output abgeschnitten wurde
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason 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).

FormatInput-TokenOutput-Token (inkl. Thinking)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − 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:

HTTPUrsacheWas zu tun ist
400Fehlendes oder ungültiges Feld; Body {"code": 400, "error": {"type": "validation_error", ...}}Anfrage korrigieren; error.details lesen
400Falsches Format für dieses Modell; die Meldung listet die unterstützten URIsChat Completions oder Gemini Native verwenden
400Gemini-Native-Fehler in Googles Form {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}contents / generationConfig korrigieren
401Fehlender oder ungültiger API-SchlüsselAuthorization-Header prüfen
402Nicht genügend CreditsVor dem erneuten Versuch aufladen
404Unbekannte Modell-ID (model_not_found)Schreibweise prüfen: gemini-4-carbon
500 / 502 / 503Server- oder Upstream-FehlerMit 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_KEY auf dem Server; liefern Sie ihn nie in Browser- oder Mobile-Code aus.
  • Setzen Sie immer max_tokens oder maxOutputTokens und loggen Sie finish_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.

Share: