Gemini 3.1 Pro API: contexto largo, herramientas y coste

Tienes una biblia de guion de 300 000 tokens para una temporada de una serie romántica para adultos y una pregunta: ¿dónde contradicen las escenas a las fichas de los personajes? Gemini 3.1 Pro Preview en SpicyAPI puede leerlo todo en una sola llamada, pero su tarifa de entrada se duplica a partir de 200 000 tokens y la de salida sube un 50 %. Envía una solicitud grande en streaming para que no alcance el tiempo de espera de las solicitudes sin streaming.

Gemini 3.1 Pro Preview (google/gemini-3.1-pro-preview/chat) admite hasta 1 000 000 de tokens de entrada, acepta partes de texto e image_url (no de PDF, vídeo ni audio), admite herramientas y salida JSON, y responde con hasta 32 768 tokens. Las tarifas de contexto largo empiezan cuando la entrada total supera los 200 000 tokens y se aplican a toda la solicitud.

Límites y tarifas

Las tarifas dependen del total de tokens de entrada: compara los niveles de facturación estándar y de contexto largo.

Deja la temperatura en su valor por defecto. Google lo recomienda para los modelos Gemini 3, y los valores más bajos pueden hacer que el modelo entre en bucle. Usa response_format y el mensaje de sistema para dar forma a la salida.

Cuánto cuesta realmente una llamada

Coste = tokens de entrada x tarifa de entrada + tokens de salida x tarifa de salida, y el nivel lo determina la entrada total (los tokens en caché cuentan). Los ejemplos usan entrada sin caché y 4 000 tokens de salida en total:

Los tokens de razonamiento se facturan como salida y comparten el presupuesto de max_tokens. Con un esfuerzo de razonamiento más alto, deja margen por encima de la respuesta visible que necesitas; un presupuesto de 4 000 tokens no garantiza 4 000 tokens de texto visible.

Un solo token por encima de 200 000 casi duplica la llamada, así que recortar 5 000 tokens de correspondencia antigua de un paquete de 203 000 tokens ahorra alrededor de un 50 %.

Tres cosas multiplican esa cifra:

• Cada ronda de herramientas reenvía el paquete. Un bucle de herramientas de tres rondas sobre un paquete de 250 000 tokens factura unos $0.90 de entrada por ronda, $2.70 en total, antes de la salida.
• Los tokens en caché son más baratos, pero aquí no se pueden controlar. La tarifa en caché ($0.36 por encima del umbral) se aplica a la entrada servida desde la caché. Por ejemplo, 300 000 tokens en caché más 5 000 nuevos y 4 000 de salida cuestan unos $0.19, frente a $1.16 sin caché. El campo cachedContent del formato Gemini se rechaza en esta ruta, así que presupuesta sin caché y comprueba el coste liquidado tras la primera ejecución.
• La retención de saldo usa todo tu max_tokens. Antes de ejecutar una solicitud de texto, la plataforma retiene la entrada más el max_tokens completo al precio del modelo: aproximadamente $4.13 para 1 000 000 de tokens de entrada y 32 768 de salida. Lee el código de error: 40201 significa saldo insuficiente para la retención; 40202, un límite de gasto. Para el primero, reduce un presupuesto de salida excesivo; para el segundo, revisa los límites de la clave y del workspace. Las URL de imagen públicas también hacen que la retención cubra todo el límite de entrada; las imágenes subidas o en línea usan una asignación fija para imágenes.

Tras la primera llamada, lee la cabecera de respuesta X-Spicy-Task-Id y consulta la tarea: su coste es definitivo cuando settled es true. Usa eso y el usage recibido en streaming para calibrar cada estimación posterior.

¿Debe entrar todo el paquete?

Envía el paquete completo cuando la respuesta dependa de relaciones a lo largo de todo el material: una auditoría de continuidad de una temporada, una pregunta de «qué ha cambiado» sobre un conjunto completo de especificaciones, una búsqueda de conflictos entre guiones y fichas de personajes. Envía solo una parte cuando la pregunta afecte a una escena o a un personaje. Una pregunta sobre el objeto de Mara en la escena 18 necesita la ficha del personaje y las escenas 12 y 18, no la temporada.

La memoria larga de una aplicación de chat puede diferir de este endpoint: la aplicación puede recuperar fragmentos seleccionados o resumir turnos antiguos, mientras que la API solo ve los mensajes enviados con la solicitud.

Una ventana de entrada grande no garantiza que se recupere cada detalle. Encontrar varios datos dispersos es más difícil que localizar uno solo, y los borradores antiguos pueden competir con la versión actual. El umbral de precio no es un límite de precisión. Para una auditoría concreta:

• Divide una temporada en arcos de hasta 150 000 tokens y audita cada uno con las mismas fichas de personajes.
• Pon la pregunta y las reglas de salida al final, después de todo el material, como recomienda Google para prompts largos.
• Etiqueta cada fragmento (SCRIPT_V3 / scene 12) y exige que las respuestas citen solo las etiquetas suministradas. Después comprueba que cada etiqueta citada existe en tu paquete.
• Pide conflictos y ubicaciones, no reescrituras. Una respuesta de 32 768 tokens no puede contener una temporada reescrita de todos modos.
• Deja fuera los borradores sustituidos. Dos versiones de la escena 12 en un mismo paquete es la forma de que un objeto antiguo se cite como vigente.

La misma lógica de presupuesto, con otras tarifas, se desarrolla en la guía de costes de Claude Sonnet 4.6 y en la guía de documentos largos con Claude Opus.

Prepara un paquete de texto

La ruta acepta partes de texto e image_url. Para comprobaciones de continuidad sobre un guion escaneado, el OCR te da texto buscable y etiquetas de escena estables: corrige los nombres y números de escena dañados antes de armar el paquete. Una URL de PDF pegada en un mensaje de texto no se lee como documento. Exporta el guion, las notas de personajes y la lista de planos como texto con etiquetas estables:

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.

Cuatro caracteres en inglés por token es una estimación aproximada de cribado, no una forma de calcular el precio de una solicitud en el umbral: el código, los nombres y el texto que no está en inglés se tokenizan de forma distinta. Deja un margen amplio por debajo de 200 000, incluye el prompt de sistema y las definiciones de herramientas en tu estimación y usa el usage devuelto para comparar el recuento real.

Convierte el hallazgo en un cambio de escena

En este paquete, la escena 12 sitúa por última vez el termo con Mara, mientras que la escena 18 se lo da a Jon sin traspaso. Una buena respuesta identifica ese hueco y ofrece una elección:

• Mostrar a Jon recogiéndolo antes de la escena 18 si el momento debe mostrar atención.
• Que Mara lo recoja ella misma si la escena debe mantener la distancia entre ambos.

Elige el momento de la relación y pide después una línea que lo ponga en práctica. El informe del modelo ayuda a localizar el hueco; el autor sigue decidiendo qué significa la acción. La auditoría no debe inventar una escena intermedia y citarla como material de origen. En una biblia de serie, el mismo enfoque detecta escenas que dan por hecha una reconciliación antes de que el guion la muestre: pide el último estado de la relación establecido, la primera escena contradictoria y la transición que falta.

Pruébalo primero en el Playground

1. Abre Gemini 3.1 Pro Preview y cambia al Playground.
2. Pega CHARACTERSV2 y las dos escenas de SCRIPTV3. Pregunta en qué punto el termo cambia de manos sin un traspaso mostrado.
3. Elige si Jon o Mara lo recoge y pide después una línea que establezca ese momento.

Envíalo en streaming

Define SPICY_API_KEY y envía el mismo paquete de escenas desde tu aplicación. El streaming evita el corte de unos 100 segundos que el edge aplica a las solicitudes sin streaming; los detalles de implementación están en la guía de 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."}
    ]
  }'

Añade una herramienta solo cuando la información esté fuera del paquete

Mantén una consulta de personajes fuera del prompt cuando el registro canónico cambie con frecuencia. Dale al modelo una función estrecha de solo lectura, como get_character, y deja que la aplicación devuelva ese registro. Limita el número de turnos: cuatro rondas sobre el mismo paquete grande pueden costar cuatro lecturas de entrada. Para una auditoría fija de dos escenas, poner los datos en el prompt es más sencillo y barato.

El grounding nativo de Search y Maps de Google son integraciones aparte; esta ruta de chat usa funciones que ejecuta tu aplicación. Las recetas de chat muestran el bucle de herramientas completo.

Deja que un Agent prepare la llamada

Para auditorías de continuidad repetidas, pide a tu Agent de programación que use el SpicyAPI Skill: «Lee google/gemini-3.1-pro-preview/chat y adapta después el ejemplo a mi entrada; muéstrame la solicitud antes de ejecutarla». La consulta con la CLI es spicyapi models get google/gemini-3.1-pro-preview/chat --json; la consulta con MCP es spicyapi_model_get con model: "google/gemini-3.1-pro-preview/chat". Las llamadas de chat usan un cliente compatible o la API de chat; los comandos de tareas multimedia no generan respuestas de chat.

Proyectos con contenido adulto

La indexación de guiones, las auditorías de continuidad y las notas de producción encajan bien. La prosa explícita es menos fiable: SpicyAPI no añade ningún filtro de contenido a esta ruta, pero el modelo puede rechazar o suavizar una petición. En nuestras pruebas de septiembre de 2026, el contenido escrito de nivel L3 se completó por entero en 1 de 3 solicitudes y la escritura de escenas íntimas, en 4 de 9. En las pruebas de escenas íntimas, el marco de ficción dentro de la solicitud se completó 3 de 3 veces, un prompt de sistema por sí solo 1 de 3 y las solicitudes directas 0 de 3. Una solicitud de ficción da a este flujo de trabajo un mejor punto de partida que depender solo del mensaje de sistema, pero elige otro modelo si lo principal que necesitas es prosa explícita fiable. La reseña de Gemini 3.1 Pro tiene el detalle.

Fallos comunes

Usa la página del modelo para ver las tarifas actuales y probar la ruta en el Playground. Es un modelo en preview, así que decide qué modelo tomará el relevo si cambia antes de que soporte tráfico de producción.