API Gemini 3.1 Pro : contexte long, outils et coût

Vous avez une bible de scénario de 300 000 tokens pour une saison d'une série romantique pour adultes et une question : où les scènes contredisent-elles les fiches des personnages ? Gemini 3.1 Pro Preview sur SpicyAPI peut tout lire en un seul appel, mais son tarif d'entrée double au-delà de 200 000 tokens et son tarif de sortie augmente de 50 %. Envoyez une grosse requête en streaming pour qu'elle n'atteigne pas le délai d'expiration des requêtes sans streaming.

Gemini 3.1 Pro Preview (google/gemini-3.1-pro-preview/chat) accepte jusqu'à 1 000 000 de tokens en entrée, admet des parties texte et image_url (pas de parties PDF, vidéo ou audio), prend en charge les outils et la sortie JSON, et répond avec jusqu'à 32 768 tokens. Les tarifs de contexte long s'appliquent lorsque l'entrée totale dépasse 200 000 tokens, et ils valent pour toute la requête.

Limites et tarifs

Les tarifs dépendent du total de tokens en entrée : comparez les paliers de facturation standard et contexte long.

Gardez la température à sa valeur par défaut. Google la recommande pour les modèles Gemini 3, et des valeurs plus basses peuvent faire boucler le modèle. Utilisez plutôt response_format et le message système pour façonner la sortie.

Ce que coûte réellement un appel

Coût = tokens en entrée x tarif d'entrée + tokens en sortie x tarif de sortie, le palier étant déterminé par l'entrée totale (les tokens en cache comptent). Les exemples utilisent une entrée sans cache et 4 000 tokens en sortie au total :

Les tokens de raisonnement sont facturés comme de la sortie et partagent le budget max_tokens. Avec un effort de raisonnement plus élevé, prévoyez de la marge au-dessus de la réponse visible dont vous avez besoin ; un budget de 4 000 tokens ne garantit pas 4 000 tokens de texte visible.

Un seul token au-delà de 200 000 double presque l'appel : retirer 5 000 tokens d'anciens échanges d'un paquet de 203 000 tokens fait donc économiser environ 50 %.

Trois éléments multiplient ce chiffre :

• Chaque tour d'outil renvoie le paquet. Une boucle d'outils de trois tours sur un paquet de 250 000 tokens facture environ $0.90 d'entrée par tour, soit $2.70 au total, avant la sortie.
• Les tokens en cache sont moins chers, mais non contrôlables ici. Le tarif en cache ($0.36 au-delà du seuil) s'applique à l'entrée servie depuis le cache. Par exemple, 300 000 tokens en cache plus 5 000 nouveaux et 4 000 en sortie coûtent environ $0.19, contre $1.16 sans cache. Le champ cachedContent au format Gemini est rejeté sur cette route : budgétez donc sans cache et vérifiez le coût réglé après le premier essai.
• Le blocage de solde utilise tout votre max_tokens. Avant l'exécution d'une requête texte, la plateforme bloque l'entrée plus la totalité de max_tokens au prix du modèle : environ $4.13 pour 1 000 000 de tokens en entrée et 32 768 en sortie. Lisez le code d'erreur : 40201 signifie un solde insuffisant pour le blocage ; 40202, un plafond de dépense. Pour le premier, réduisez un budget de sortie excessif ; pour le second, examinez les plafonds de la clé et du workspace. Les URL d'images publiques font aussi couvrir par le blocage toute la limite d'entrée ; les images téléversées ou intégrées utilisent à la place une enveloppe fixe pour les images.

Après le premier appel, lisez l'en-tête de réponse X-Spicy-Task-Id et consultez la tâche : son coût est définitif lorsque settled vaut true. Servez-vous-en, ainsi que du usage diffusé en streaming, pour calibrer chaque estimation suivante.

Faut-il tout envoyer ?

Envoyez le paquet entier quand la réponse dépend de relations à travers tout le matériel : un audit de continuité sur une saison, une question « qu'est-ce qui a changé » sur un jeu complet de spécifications, une recherche de conflits entre scénarios et fiches de personnages. Envoyez un extrait quand la question ne touche qu'une scène ou un personnage. Une question sur l'accessoire de Mara à la scène 18 demande la fiche du personnage et les scènes 12 et 18, pas la saison.

La mémoire longue d'une application de chat peut différer de cet endpoint : l'application peut récupérer des passages choisis ou résumer d'anciens tours, tandis que l'API ne voit que les messages envoyés avec la requête.

Une grande fenêtre d'entrée ne garantit pas que chaque détail sera retrouvé. Retrouver plusieurs faits dispersés est plus difficile que d'en localiser un seul, et d'anciens brouillons peuvent concurrencer la version actuelle. Le seuil de prix n'est pas une frontière de précision. Pour un audit ciblé :

• Découpez une saison en arcs d'au plus 150 000 tokens et auditez chacun avec les mêmes fiches de personnages.
• Placez la question et les règles de sortie à la fin, après tout le matériel, comme Google le recommande pour les longs prompts.
• Étiquetez chaque morceau (SCRIPT_V3 / scene 12) et exigez que les réponses ne citent que les étiquettes fournies. Vérifiez ensuite que chaque étiquette citée existe dans votre paquet.
• Demandez des conflits et des emplacements, pas des réécritures. Une réponse de 32 768 tokens ne peut de toute façon pas contenir une saison réécrite.
• Écartez les brouillons remplacés. Deux versions de la scène 12 dans un même paquet, c'est ainsi qu'un ancien accessoire est cité comme actuel.

La même logique de budget, avec d'autres tarifs, est détaillée dans le guide des coûts de Claude Sonnet 4.6 et le guide Claude Opus pour les longs documents.

Préparer un paquet de texte

La route accepte des parties texte et image_url. Pour des contrôles de continuité sur un scénario numérisé, l'OCR fournit du texte consultable et des étiquettes de scène stables : corrigez les noms et numéros de scène abîmés avant de constituer le paquet. Une URL de PDF collée dans un message texte n'est pas lue comme un document. Exportez le scénario, les notes de personnages et la liste de plans en texte avec des étiquettes stables :

CHARACTERS_V2
Mara: 32, photographer. Keeps a copper thermos with a blue band.
Jon: 35, composer. Owns the red leather case.

SCRIPT_V3 / scene 12
Mara puts the thermos on the railway bench. Jon carries the case.

SCRIPT_V3 / scene 18
Jon offers Mara the thermos.

Quatre caractères anglais par token constituent une estimation grossière de présélection, pas un moyen de chiffrer une requête au seuil : le code, les noms et le texte non anglais sont découpés différemment. Gardez une large marge sous 200 000, incluez le prompt système et les définitions d'outils dans votre estimation, et utilisez le usage renvoyé pour comparer le décompte réel.

Transformer la découverte en modification de scène

Dans ce paquet, la scène 12 situe en dernier lieu le thermos chez Mara, tandis que la scène 18 le donne à Jon sans transmission. Une bonne réponse repère cet écart et propose un choix :

• Montrer Jon en train de le récupérer avant la scène 18 si le moment doit montrer de l'attention.
• Faire récupérer le thermos par Mara elle-même si la scène doit préserver la distance entre eux.

Choisissez le moment de la relation, puis demandez une réplique qui le met en œuvre. Le rapport du modèle aide à repérer l'écart ; c'est l'auteur qui décide de ce que l'action signifie. L'audit ne doit pas inventer une scène intermédiaire et la citer comme matériau source. Pour une bible de série, la même approche détecte les scènes qui supposent une réconciliation avant que le scénario la montre : demandez le dernier état de la relation établi, la première scène contradictoire et la transition manquante.

Essayer d'abord dans le Playground

1. Ouvrez Gemini 3.1 Pro Preview et passez au Playground.
2. Collez CHARACTERSV2 et les deux scènes de SCRIPTV3. Demandez à quel endroit le thermos change de mains sans transfert montré.
3. Choisissez si c'est Jon ou Mara qui le récupère, puis demandez une réplique qui établit ce moment.

L'envoyer en streaming

Définissez SPICY_API_KEY et envoyez le même paquet de scènes depuis votre application. Le streaming évite la coupure d'environ 100 secondes appliquée en périphérie aux requêtes sans streaming ; les détails d'implémentation figurent dans le guide du chat.

INTENT_KEY=$(uuidgen)
curl --fail-with-body -sN --max-time 600 https://api.spicyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $INTENT_KEY" \
  -D reply.headers -o reply.sse \
  -d '{
    "model": "google/gemini-3.1-pro-preview/chat",
    "stream": true,
    "stream_options": {"include_usage": true},
    "reasoning_effort": "low",
    "max_tokens": 4000,
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Return JSON with conflicts and suggested_fixes arrays. Cite only supplied scene labels. Do not invent missing scenes."},
      {"role": "user", "content": "Fictional adults: Mara, 32, and Jon, 35. SCRIPT_V3 / scene 12: Mara leaves her blue-banded copper thermos on the railway bench. Jon carries his red case. SCRIPT_V3 / scene 18: Jon hands Mara the thermos. Identify any missing prop handoff."}
    ]
  }'

N'ajoutez un outil que si l'information est hors du paquet

Gardez une recherche de personnage hors du prompt lorsque la fiche de référence change souvent. Donnez au modèle une fonction étroite en lecture seule, comme get_character, et laissez l'application renvoyer cette fiche. Plafonnez le nombre de tours : quatre tours sur le même gros paquet peuvent coûter quatre lectures d'entrée. Pour un audit fixe de deux scènes, mettre les faits dans le prompt est plus simple et moins cher.

Le grounding natif Search et Maps de Google relève d'intégrations distinctes ; cette route de chat utilise des fonctions que votre application exécute. Les recettes de chat montrent la boucle d'outils complète.

Laisser un Agent préparer l'appel

Pour des audits de continuité répétés, demandez à votre Agent de code d'utiliser le SpicyAPI Skill : « Lis google/gemini-3.1-pro-preview/chat, puis adapte l'exemple à mon entrée ; montre-moi la requête avant de l'exécuter. » La consultation via la CLI est spicyapi models get google/gemini-3.1-pro-preview/chat --json ; via MCP, c'est spicyapi_model_get avec model: "google/gemini-3.1-pro-preview/chat". Les appels de chat passent par un client compatible ou l'API de chat ; les commandes de tâches média ne génèrent pas de réponses de chat.

Projets avec contenu adulte

L'indexation de scénarios, les audits de continuité et les notes de production conviennent bien. La prose explicite est moins fiable : SpicyAPI n'ajoute aucun filtre de contenu à cette route, mais le modèle peut refuser ou atténuer une demande. Lors de nos tests de septembre 2026, le contenu écrit de niveau L3 a été produite en entier dans 1 requête sur 3, et l'écriture de scènes intimes dans 4 sur 9. Pour les tests de scènes intimes, un cadrage fictionnel dans la requête a abouti 3 fois sur 3, un prompt système seul 1 fois sur 3 et les demandes directes 0 fois sur 3. Une demande de fiction offre à ce flux de travail un meilleur point de départ que de se fier au seul message système, mais choisissez un autre modèle si une prose explicite fiable est le livrable principal. L'avis sur Gemini 3.1 Pro en donne le détail.

Échecs courants

Utilisez la page du modèle pour les tarifs actuels et pour essayer la route dans le Playground. C'est un modèle en preview : décidez donc quel modèle prendra le relais s'il change avant qu'il ne porte du trafic de production.