
Ce guide de la Gemini 4 Carbon API vous mène d’une clé API à une requête fonctionnelle en cURL, avec le SDK OpenAI en Python et dans le format natif generateContent de Google, toujours avec l’identifiant de modèle gemini-4-carbon. Chaque exemple suit le schéma de requête publié par PoYo au 16 novembre 2026. Vous pouvez d’abord tester vos prompts sur la page du modèle Gemini 4 Carbon.
Vous découvrez le modèle ? Commencez par la présentation de la Gemini 4 Carbon API pour ses limites et son positionnement.
Avant de commencer
Créez une clé dans le tableau de bord PoYo et conservez-la sur votre serveur :
export POYO_API_KEY="your-poyo-key"
| Format | Endpoint | Quand l’utiliser |
|---|---|---|
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Vous utilisez déjà le SDK OpenAI, messages texte uniquement |
| Gemini Native | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContent | Vous avez besoin de parties image ou fichier (inlineData) |
| Gemini Native en streaming | POST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContent | Format natif avec server-sent events |
Chaque requête envoie Authorization: Bearer $POYO_API_KEY. Sur PoYo, gemini-4-carbon ne prend pas en charge /v1/responses ni /v1/messages.
Première requête à la Gemini 4 Carbon API avec 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 et messages sont obligatoires. Champs facultatifs du schéma PoYo : temperature (0–2), top_p (0–1 ; utilisez-le ou temperature, pas les deux), max_tokens, stream, stop (jusqu’à 4 séquences), frequency_penalty et presence_penalty (−2 à 2), et n. Le content de chaque message est une chaîne.
La réponse est un objet chat.completion standard : le texte dans choices[0].message.content, la cause d’arrêt dans choices[0].finish_reason, et les décomptes dans usage.prompt_tokens, usage.completion_tokens et usage.total_tokens.
Python avec le SDK OpenAI
Pointez le SDK vers PoYo, sans rien changer d’autre :
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)
Passer de gemini-4-argon, ou de tout autre modèle qui prend en charge Chat Completions sur PoYo, se résume à modifier une ligne : model.
Streaming avec le SDK OpenAI
Avec stream=True, PoYo envoie des événements chat.completion.chunk et termine par data: [DONE]. Le texte arrive dans choices[0].delta.content, et le dernier chunk contient finish_reason et 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)
Le format natif Gemini generateContent
L’endpoint natif prend le modèle dans le chemin de l’URL. Le corps utilise contents (chacun avec un role user ou model et un tableau parts), ainsi que generationConfig (temperature, topP, topK, maxOutputTokens, stopSequences) et safetySettings, facultatifs :
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}
}'
La réponse est l’objet GenerateContentResponse de Google, renvoyé tel quel. Le texte se trouve dans candidates[].content.parts[].text et les décomptes dans usageMetadata. Les modèles à réflexion peuvent ajouter des parties avec thought: true ou une thoughtSignature ; ignorez donc les parties sans texte :
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"])
Streaming natif
Remplacez la méthode par :streamGenerateContent. La réponse est en text/event-stream : chaque ligne data: est une GenerateContentResponse partielle, le dernier événement contient finishReason, et le flux se termine par data: [DONE]. Le paramètre de requête alt=sse est accepté mais pas obligatoire.
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)
Entrée multimodale avec la Gemini 4 Carbon API
Google indique le texte, l’image, l’audio, la vidéo et le PDF comme types d’entrée pour Gemini 4 Carbon. Sur PoYo, l’entrée de fichiers passe par le format natif, sous forme de partie inlineData avec un mimeType et des data en base64. La documentation de PoYo montre un exemple d’image et recommande de placer les instructions textuelles avant les parties média :
{
"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}
}
Le schéma Chat Completions de PoYo documente content comme une chaîne : n’envoyez donc pas de tableaux d’images à la manière d’OpenAI vers /v1/chat/completions. Pour le PDF, l’audio et la vidéo, la documentation de PoYo ne montre pas d’exemple distinct ; envoyez d’abord un petit fichier et vérifiez la réponse avant de bâtir un pipeline dessus. Les médias comptent dans le prompt : usageMetadata.promptTokensDetails ventile les tokens du prompt par modalité.
Régler la sortie maximale
| Format | Champ | Signe que la sortie a été tronquée |
|---|---|---|
| Chat Completions | max_tokens | finish_reason: "length" |
| Gemini Native | generationConfig.maxOutputTokens | finishReason différent de STOP |
Google indique 65 536 tokens de sortie comme plafond synchrone par défaut et un contexte de 1 048 576 tokens partagé entre entrée et sortie. La page de tarification de Google précise que les tokens de réflexion sont facturés au tarif de sortie : le nombre de tokens de sortie dans usage peut donc dépasser le texte visible. Les schémas publiés par PoYo n’ont pas de champ de niveau de réflexion ; le champ de sortie maximale est le contrôle de longueur documenté.
Lire l’usage et calculer le coût d’une requête
PoYo facture gemini-4-carbon 1,60 $ par million de tokens en entrée, 8,00 $ par million de tokens en sortie et 0,08 $ par million de tokens lus depuis le cache (1 crédit = 0,005 $).
| Format | Tokens d’entrée | Tokens de sortie (réflexion incluse) |
|---|---|---|
| Chat Completions | usage.prompt_tokens | usage.total_tokens − usage.prompt_tokens |
| Gemini Native | usageMetadata.promptTokenCount | totalTokenCount − promptTokenCount (réponse 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
Exemple mesuré (production PoYo, 16 novembre 2026) : une requête /v1/chat/completions sans streaming demandant à gemini-4-carbon de relire une fonction Python de 40 lignes a renvoyé prompt_tokens: 480, completion_tokens: 1094 et total_tokens: 1574 en 6,3 secondes, sans jetons de réflexion signalés. PoYo a facturé 1,904 crédit, le même chiffre que la 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)
Ce calcul facture chaque token du prompt au plein tarif d’entrée. Les tokens lus depuis le cache sont facturés 0,08 $ par million, mais les schémas de réponse de PoYo ne documentent aucun champ de tokens en cache : considérez donc cette formule comme une borne supérieure. Des scénarios de coût à grande échelle figurent dans Prix de la Gemini 4 Carbon API.
Les erreurs à gérer
Les endpoints LLM de PoYo renvoient de vrais codes de statut HTTP :
| HTTP | Cause | Que faire |
|---|---|---|
| 400 | Champ manquant ou invalide ; corps {"code": 400, "error": {"type": "validation_error", ...}} | Corrigez la requête ; lisez error.details |
| 400 | Format incorrect pour ce modèle ; le message liste les URI prises en charge | Utilisez Chat Completions ou Gemini Native |
| 400 | Erreur Gemini Native, au format Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}} | Corrigez contents / generationConfig |
| 401 | Clé API manquante ou invalide | Vérifiez l’en-tête Authorization |
| 402 | Crédits insuffisants | Rechargez avant de réessayer |
| 404 | Identifiant de modèle inconnu (model_not_found) | Vérifiez l’orthographe : gemini-4-carbon |
| 500 / 502 / 503 | Erreur serveur ou en amont | Réessayez avec un backoff exponentiel |
La documentation de PoYo indique que les endpoints LLM ne sont actuellement pas soumis à des limites de débit, mais les codes d’erreur généraux de PoYo incluent 429. Gérez-le par une attente suivie d’une nouvelle tentative. Avec le SDK OpenAI, interceptez openai.APIStatusError et branchez sur status_code. Consultez les codes d’erreur PoYo pour les corps complets.
Liste de contrôle avant la mise en production
- Gardez
POYO_API_KEYcôté serveur ; ne l’intégrez jamais dans du code navigateur ou mobile. - Définissez toujours
max_tokensoumaxOutputTokens, et journalisezfinish_reason/finishReasonpour que les réponses tronquées soient visibles. - Stockez le bloc d’usage de chaque réponse à côté de l’identifiant de requête que vous attribuez, afin de rapprocher les dépenses par fonctionnalité.
- Placez le contexte long et stable (fichiers du dépôt, documents) en premier et la question variable en dernier, pour laisser une chance à la mise en cache implicite.
- Ne réessayez que les réponses 5xx et
429; une erreur 400 échouera de nouveau tant que le corps ne change pas.
Pour les boucles d’agents, la sortie des outils et les schémas à long contexte, poursuivez avec Gemini 4 Carbon API pour les agents de code. Pour savoir quand Argon suffit, lisez Gemini 4 Carbon API vs Gemini 4 Argon.
Questions fréquentes
Comment appeler la Gemini 4 Carbon API en Python ?
Utilisez le SDK OpenAI avec base_url="https://api.poyo.ai/v1", votre clé PoYo et model="gemini-4-carbon". Pour les requêtes natives, envoyez un POST vers /v1beta/models/gemini-4-carbon:generateContent avec requests.
La Gemini 4 Carbon API prend-elle en charge le streaming ?
Oui. Définissez "stream": true sur Chat Completions, ou appelez :streamGenerateContent au format natif. Les deux renvoient des server-sent events qui se terminent par data: [DONE].
Comment envoyer une image à la Gemini 4 Carbon API ?
Utilisez l’endpoint natif Gemini avec une partie inlineData (mimeType plus data en base64) placée après votre partie texte. Sur PoYo, Chat Completions n’accepte qu’un contenu sous forme de chaîne.
Comment limiter les tokens de sortie de la Gemini 4 Carbon API ?
Définissez max_tokens (Chat Completions) ou generationConfig.maxOutputTokens (natif). Les tokens de réflexion sont facturés comme sortie : comparez donc le nombre de tokens de sortie dans usage avec le texte visible pour choisir le plafond.
Pourquoi la Gemini 4 Carbon API renvoie-t-elle 400 sur /v1/responses ?
Sur PoYo, gemini-4-carbon ne prend en charge que Chat Completions et Gemini Native. Les autres formats renvoient 400 avec la liste des URI prises en charge.