how-tos

Gemini 4 Carbon API-gids: je eerste verzoek met cURL, Python en Gemini Native

Poyo.ai Team
9 min read
Share:

Gemini 4 Carbon API-gids: eerste verzoek met cURL en Python

Deze gids voor de Gemini 4 Carbon API brengt je van een API-sleutel naar een werkend verzoek met cURL, de Python OpenAI SDK en Googles native generateContent-formaat, allemaal met de model-ID gemini-4-carbon. Elk voorbeeld volgt het gepubliceerde verzoekschema van PoYo zoals dat gold op 16 november 2026. Je kunt prompts eerst testen op de Gemini 4 Carbon-modelpagina.

Nieuw met dit model? Begin met het overzicht van de Gemini 4 Carbon API voor limieten en positionering.

Voordat je begint

Maak een sleutel aan in het PoYo-dashboard en bewaar hem op je server:

export POYO_API_KEY="your-poyo-key"
FormaatEndpointGebruik het als
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsJe de OpenAI SDK al gebruikt en alleen tekstberichten stuurt
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentJe afbeeldings- of bestandsparts (inlineData) nodig hebt
Gemini Native-streamingPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentNative formaat met server-sent events

Elk verzoek stuurt Authorization: Bearer $POYO_API_KEY mee. gemini-4-carbon ondersteunt op PoYo geen /v1/responses of /v1/messages.

Je eerste verzoek aan de Gemini 4 Carbon API met 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 en messages zijn verplicht. Optionele velden in het schema van PoYo: temperature (0–2), top_p (0–1; gebruik dit of temperature, niet allebei), max_tokens, stream, stop (maximaal 4 reeksen), frequency_penalty en presence_penalty (−2 tot 2), en n. De content van elk bericht is een string.

Het antwoord is een standaard chat.completion-object: de tekst in choices[0].message.content, de stopreden in choices[0].finish_reason en de aantallen in usage.prompt_tokens, usage.completion_tokens en usage.total_tokens.

Python met de OpenAI SDK

Laat de SDK naar PoYo wijzen en verander verder niets:

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)

Overstappen van gemini-4-argon, of van elk ander model dat op PoYo Chat Completions ondersteunt, is een wijziging van één regel in model.

Streaming met de OpenAI SDK

Met stream=True stuurt PoYo chat.completion.chunk-events en sluit af met data: [DONE]. De tekst komt binnen in choices[0].delta.content, en de laatste chunk bevat finish_reason en 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)

Het Gemini-native generateContent-formaat

Bij het native endpoint staat het model in het URL-pad. De body gebruikt contents (elk met role user of model en een parts-array), plus optioneel generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) en 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}
  }'

Het antwoord is Googles GenerateContentResponse-object, dat direct wordt teruggegeven. De tekst staat in candidates[].content.parts[].text en de aantallen in usageMetadata. Thinking-modellen kunnen parts toevoegen met thought: true of een thoughtSignature, dus sla parts zonder tekst over:

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"])

Native streaming

Vervang de methode door :streamGenerateContent. Het antwoord is text/event-stream: elke data:-regel is een gedeeltelijke GenerateContentResponse, het laatste event bevat finishReason, en de stream eindigt met data: [DONE]. De queryparameter alt=sse wordt geaccepteerd, maar is niet verplicht.

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)

Multimodale input via de Gemini 4 Carbon API

Google noemt tekst, afbeelding, audio, video en PDF als inputtypes voor Gemini 4 Carbon. Op PoYo gaat bestandsinput via het native formaat als een inlineData-part met een mimeType en base64-gecodeerde data. De documentatie van PoYo toont een voorbeeld met een afbeelding en raadt aan tekstinstructies vóór de mediaparts te zetten:

{
  "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}
}

Het Chat Completions-schema van PoYo documenteert content als een string, dus stuur geen afbeeldingsarrays in OpenAI-stijl naar /v1/chat/completions. Voor PDF, audio en video toont de documentatie van PoYo geen apart voorbeeld; stuur eerst één klein bestand en controleer het antwoord voordat je er een pipeline op bouwt. Media tellen mee voor de prompt: usageMetadata.promptTokensDetails splitst de prompt-tokens uit per modaliteit.

De maximale output instellen

FormaatVeldSignaal dat de output is afgekapt
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason anders dan STOP

Google noemt 65.536 output-tokens als standaardlimiet voor synchrone verzoeken en een context van 1.048.576 tokens die input en output delen. Volgens Googles prijspagina worden thinking-tokens tegen het outputtarief gefactureerd, dus het outputaantal in usage kan groter zijn dan de zichtbare tekst. De gepubliceerde schema's van PoYo hebben geen veld voor het thinking level; het veld voor de maximale output is de gedocumenteerde manier om de lengte te sturen.

Usage uitlezen en de kosten van een verzoek berekenen

PoYo rekent voor gemini-4-carbon $1.60 per 1M input-tokens, $8.00 per 1M output-tokens en $0.08 per 1M cache-read-tokens (1 credit = $0.005).

FormaatInput-tokensOutput-tokens (incl. thinking)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − promptTokenCount (antwoord 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

Gemeten voorbeeld (PoYo-productie, 16 november 2026): een niet-streamend /v1/chat/completions-verzoek waarin gemini-4-carbon een Python-functie van 40 regels moest reviewen, gaf prompt_tokens: 480, completion_tokens: 1094 en total_tokens: 1574 terug in 6,3 seconden, zonder gerapporteerde thinking-tokens. PoYo rekende 1,904 credits af, hetzelfde getal als de formule.

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 wordt elk prompt-token tegen het volledige inputtarief berekend. Cache-read-tokens kosten $0.08 per 1M, maar de antwoordschema's van PoYo documenteren geen veld voor gecachete tokens, dus beschouw deze formule als een bovengrens. Kostenscenario's op schaal staan in Gemini 4 Carbon API-prijzen.

Fouten die je moet afhandelen

LLM-endpoints op PoYo geven echte HTTP-statuscodes terug:

HTTPOorzaakWat te doen
400Ontbrekend of ongeldig veld; body {"code": 400, "error": {"type": "validation_error", ...}}Verzoek corrigeren; error.details lezen
400Verkeerd formaat voor dit model; de melding noemt de ondersteunde URI'sChat Completions of Gemini Native gebruiken
400Gemini Native-fout in Googles vorm {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}contents / generationConfig corrigeren
401Ontbrekende of ongeldige API-sleutelDe Authorization-header controleren
402Onvoldoende creditsOpwaarderen voordat je het opnieuw probeert
404Onbekende model-ID (model_not_found)Spelling controleren: gemini-4-carbon
500 / 502 / 503Server- of upstreamfoutOpnieuw proberen met exponentiële backoff

Volgens de documentatie van PoYo hebben LLM-endpoints momenteel geen rate limit, maar de algemene foutcodes van PoYo bevatten wel 429. Handel die af door te wachten en opnieuw te proberen. Met de OpenAI SDK vang je openai.APIStatusError af en vertak je op status_code. Zie de PoYo-foutcodes voor de volledige bodies.

Checklist voordat je live gaat

  • Houd POYO_API_KEY aan de serverkant; lever hem nooit mee in browser- of mobiele code.
  • Stel altijd max_tokens of maxOutputTokens in en log finish_reason / finishReason, zodat afgekapte antwoorden zichtbaar worden.
  • Sla het usage-blok van elk antwoord op naast de request-ID die je zelf toekent, zodat je de kosten per feature kunt afstemmen.
  • Zet lange, stabiele context (repositorybestanden, documenten) vooraan en de wisselende vraag achteraan; dan heeft impliciete caching een kans om te werken.
  • Probeer alleen 5xx- en 429-antwoorden opnieuw; een 400 blijft mislukken tot de body verandert.

Voor agentlussen, tooloutput en patronen met lange context lees je verder in Gemini 4 Carbon API voor coding agents. Om te bepalen wanneer Argon volstaat, lees Gemini 4 Carbon API vs. Gemini 4 Argon.

Veelgestelde vragen

Hoe roep ik de Gemini 4 Carbon API aan in Python?

Gebruik de OpenAI SDK met base_url="https://api.poyo.ai/v1", je PoYo-sleutel en model="gemini-4-carbon". Voor native verzoeken doe je met requests een POST naar /v1beta/models/gemini-4-carbon:generateContent.

Ondersteunt de Gemini 4 Carbon API streaming?

Ja. Zet "stream": true bij Chat Completions, of roep :streamGenerateContent aan in het native formaat. Beide geven server-sent events terug die eindigen met data: [DONE].

Hoe stuur ik een afbeelding naar de Gemini 4 Carbon API?

Gebruik het Gemini-native endpoint met een inlineData-part (mimeType plus base64-gecodeerde data) na je tekstpart. Chat Completions accepteert op PoYo alleen stringcontent.

Hoe beperk ik de output-tokens van de Gemini 4 Carbon API?

Stel max_tokens (Chat Completions) of generationConfig.maxOutputTokens (native) in. Thinking-tokens worden als output gefactureerd, dus vergelijk bij het kiezen van de limiet het outputaantal in usage met de zichtbare tekst.

Waarom geeft de Gemini 4 Carbon API een 400 terug op /v1/responses?

gemini-4-carbon ondersteunt op PoYo alleen Chat Completions en Gemini Native. Andere formaten geven een 400 terug met de lijst van ondersteunde URI's.

Share: