
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"
| Formaat | Endpoint | Gebruik het als |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Je de OpenAI SDK al gebruikt en alleen tekstberichten stuurt |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Je afbeeldings- of bestandsparts (inlineData) nodig hebt |
| Gemini Native-streaming | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Native 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
| Formaat | Veld | Signaal dat de output is afgekapt |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason 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).
| Formaat | Input-tokens | Output-tokens (incl. thinking) |
|---|---|---|
| Chat Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − 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:
| HTTP | Oorzaak | Wat te doen |
|---|---|---|
| 400 | Ontbrekend of ongeldig veld; body {"code": 400, "error": {"type": "validation_error", ...}} | Verzoek corrigeren; error.details lezen |
| 400 | Verkeerd formaat voor dit model; de melding noemt de ondersteunde URI's | Chat Completions of Gemini Native gebruiken |
| 400 | Gemini Native-fout in Googles vorm {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | contents / generationConfig corrigeren |
| 401 | Ontbrekende of ongeldige API-sleutel | De Authorization-header controleren |
| 402 | Onvoldoende credits | Opwaarderen voordat je het opnieuw probeert |
| 404 | Onbekende model-ID (model_not_found) | Spelling controleren: gemini-4-carbon |
| 500 / 502 / 503 | Server- of upstreamfout | Opnieuw 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_KEYaan de serverkant; lever hem nooit mee in browser- of mobiele code. - Stel altijd
max_tokensofmaxOutputTokensin en logfinish_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.