how-tos

Gemini 4 Carbon API : guide de la première requête en cURL, Python et Gemini Native

Poyo.ai Team
10 min read
Share:

Guide de la Gemini 4 Carbon API : première requête en cURL et en Python

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"
FormatEndpointQuand l’utiliser
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsVous utilisez déjà le SDK OpenAI, messages texte uniquement
Gemini NativePOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:generateContentVous avez besoin de parties image ou fichier (inlineData)
Gemini Native en streamingPOST https://api.poyo.ai/v1beta/models/gemini-4-carbon:streamGenerateContentFormat 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

FormatChampSigne que la sortie a été tronquée
Chat Completionsmax_tokensfinish_reason: "length"
Gemini NativegenerationConfig.maxOutputTokensfinishReason 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 $).

FormatTokens d’entréeTokens de sortie (réflexion incluse)
Chat Completionsusage.prompt_tokensusage.total_tokens − usage.prompt_tokens
Gemini NativeusageMetadata.promptTokenCounttotalTokenCount − 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 :

HTTPCauseQue faire
400Champ manquant ou invalide ; corps {"code": 400, "error": {"type": "validation_error", ...}}Corrigez la requête ; lisez error.details
400Format incorrect pour ce modèle ; le message liste les URI prises en chargeUtilisez Chat Completions ou Gemini Native
400Erreur Gemini Native, au format Google {"error": {"code": 400, "message": "...", "status": "INVALID_ARGUMENT"}}Corrigez contents / generationConfig
401Clé API manquante ou invalideVérifiez l’en-tête Authorization
402Crédits insuffisantsRechargez avant de réessayer
404Identifiant de modèle inconnu (model_not_found)Vérifiez l’orthographe : gemini-4-carbon
500 / 502 / 503Erreur serveur ou en amontRé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_KEY côté serveur ; ne l’intégrez jamais dans du code navigateur ou mobile.
  • Définissez toujours max_tokens ou maxOutputTokens, et journalisez finish_reason / finishReason pour 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.

Share: