API do Gemini 3.1 Pro: contexto longo, ferramentas e custo

Você tem uma bíblia de roteiro de 300.000 tokens para uma temporada de uma série romântica para adultos e uma pergunta: onde as cenas contradizem as fichas dos personagens? O Gemini 3.1 Pro Preview na SpicyAPI consegue ler tudo em uma única chamada, mas a tarifa de entrada dobra acima de 200.000 tokens e a de saída sobe 50%. Envie uma requisição grande em streaming para que ela não atinja o timeout das requisições sem streaming.

O Gemini 3.1 Pro Preview (google/gemini-3.1-pro-preview/chat) aceita até 1.000.000 de tokens de entrada, aceita partes de texto e image_url (não partes de PDF, vídeo ou áudio), oferece suporte a ferramentas e saída JSON e responde com até 32.768 tokens. As tarifas de contexto longo começam quando a entrada total excede 200.000 tokens e valem para a requisição inteira.

Limites e tarifas

As tarifas dependem do total de tokens de entrada: compare as faixas de cobrança padrão e de contexto longo.

Mantenha a temperatura no valor padrão. O Google a recomenda para os modelos Gemini 3, e valores mais baixos podem fazer o modelo entrar em loop. Use response_format e a mensagem de sistema para moldar a saída.

Quanto uma chamada realmente custa

Custo = tokens de entrada x tarifa de entrada + tokens de saída x tarifa de saída, com a faixa definida pela entrada total (tokens em cache contam). Os exemplos usam entrada sem cache e 4.000 tokens de saída no total:

Os tokens de raciocínio são cobrados como saída e dividem o orçamento de max_tokens. Com esforço de raciocínio maior, deixe folga acima da resposta visível de que você precisa; um orçamento de 4.000 tokens não garante 4.000 tokens de texto visível.

Um único token acima de 200.000 quase dobra a chamada, então cortar 5.000 tokens de correspondência antiga de um pacote de 203.000 tokens economiza cerca de 50%.

Três coisas multiplicam esse número:

• Cada rodada de ferramenta reenvia o pacote. Um ciclo de ferramentas de três rodadas sobre um pacote de 250.000 tokens cobra cerca de $0,90 de entrada por rodada, $2,70 no total, antes da saída.
• Tokens em cache são mais baratos, mas aqui não dá para controlá-los. A tarifa de cache ($0,36 acima do limite) vale para a entrada atendida pelo cache. Por exemplo, 300.000 tokens em cache mais 5.000 novos e 4.000 de saída custam cerca de $0,19, contra $1,16 sem cache. O campo cachedContent do formato Gemini é rejeitado nesta rota, então orce sem cache e confira o custo liquidado após a primeira execução.
• A retenção de saldo usa todo o seu max_tokens. Antes de uma requisição de texto rodar, a plataforma retém a entrada mais o max_tokens completo ao preço do modelo: aproximadamente $4,13 para 1.000.000 de tokens de entrada e 32.768 de saída. Leia o código de erro: 40201 significa saldo insuficiente para a retenção; 40202, um limite de gasto. Para o primeiro, reduza um orçamento de saída excessivo; para o segundo, verifique os limites da chave e do workspace. URLs de imagens públicas também fazem a retenção cobrir todo o limite de entrada; imagens enviadas por upload ou inline usam, em vez disso, uma reserva fixa para imagens.

Depois da primeira chamada, leia o cabeçalho de resposta X-Spicy-Task-Id e consulte a tarefa: o custo é definitivo quando settled é true. Use isso e o usage recebido em streaming para calibrar toda estimativa seguinte.

O pacote inteiro deve entrar?

Envie o pacote inteiro quando a resposta depender de relações ao longo de todo o material: uma auditoria de continuidade de uma temporada, uma pergunta de «o que mudou» sobre um conjunto completo de especificações, uma busca de conflitos entre roteiros e fichas de personagens. Envie um trecho quando a pergunta tocar uma cena ou um personagem. Uma pergunta sobre o objeto de cena de Mara na cena 18 precisa da ficha do personagem e das cenas 12 e 18, não da temporada.

A memória longa de um aplicativo de chat pode ser diferente deste endpoint: o aplicativo pode recuperar trechos selecionados ou resumir turnos antigos, enquanto a API vê apenas as mensagens enviadas com a requisição.

Uma janela de entrada grande não garante que cada detalhe seja recuperado. Encontrar vários fatos espalhados é mais difícil do que localizar um só, e rascunhos antigos podem competir com a versão atual. O limite de preço não é um limite de precisão. Para uma auditoria focada:

• Divida uma temporada em arcos de até 150.000 tokens e audite cada um com as mesmas fichas de personagens.
• Coloque a pergunta e as regras de saída por último, depois de todo o material, como o Google recomenda para prompts longos.
• Rotule cada trecho (SCRIPT_V3 / scene 12) e exija que as respostas citem apenas os rótulos fornecidos. Depois verifique se cada rótulo citado existe no seu pacote.
• Peça conflitos e localizações, não reescritas. Uma resposta de 32.768 tokens não comporta uma temporada reescrita de qualquer forma.
• Deixe de fora os rascunhos substituídos. Duas versões da cena 12 no mesmo pacote são o jeito de um objeto antigo ser citado como atual.

A mesma lógica de orçamento, com outras tarifas, é desenvolvida no guia de custos do Claude Sonnet 4.6 e no guia do Claude Opus para documentos longos.

Prepare um pacote de texto

A rota aceita partes de texto e image_url. Para verificações de continuidade em um roteiro digitalizado, o OCR fornece texto pesquisável e rótulos de cena estáveis: corrija nomes e números de cena danificados antes de montar o pacote. Uma URL de PDF colada em uma mensagem de texto não é lida como documento. Exporte o roteiro, as notas de personagens e a lista de planos como texto com rótulos estáveis:

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.

Quatro caracteres em inglês por token são uma estimativa grosseira de triagem, não uma forma de precificar uma requisição no limite: código, nomes e texto que não esteja em inglês são tokenizados de maneira diferente. Deixe bastante folga abaixo de 200.000, inclua o prompt de sistema e as definições de ferramentas na estimativa e use o usage retornado para comparar a contagem real.

Transforme a descoberta em uma mudança de cena

Neste pacote, a cena 12 situa por último a garrafa térmica com a Mara, enquanto a cena 18 a entrega ao Jon sem uma passagem de mãos. Uma resposta útil identifica essa lacuna e oferece uma escolha:

• Mostrar o Jon pegando-a antes da cena 18 se o momento deve mostrar atenção.
• Fazer a própria Mara pegá-la se a cena deve preservar a distância entre os dois.

Escolha o momento da relação e depois peça uma fala que o realize. O relatório do modelo ajuda a localizar a lacuna; quem decide o que a ação significa continua sendo o autor. A auditoria não deve inventar uma cena intermediária e citá-la como material de origem. Em uma bíblia de série, a mesma abordagem encontra cenas que pressupõem uma reconciliação antes de o roteiro mostrá-la: peça o último estado da relação estabelecido, a primeira cena contraditória e a transição que falta.

Experimente primeiro no Playground

1. Abra o Gemini 3.1 Pro Preview e mude para o Playground.
2. Cole CHARACTERSV2 e as duas cenas de SCRIPTV3. Pergunte onde a garrafa térmica muda de mãos sem uma passagem mostrada.
3. Escolha se o Jon ou a Mara a pega e depois peça uma fala que estabeleça esse momento.

Envie em streaming

Defina SPICY_API_KEY e envie o mesmo pacote de cenas a partir do seu app. O streaming evita o corte de cerca de 100 segundos que o edge aplica a requisições sem streaming; os detalhes de implementação estão no guia 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."}
    ]
  }'

Adicione uma ferramenta somente quando a informação estiver fora do pacote

Mantenha uma consulta de personagem fora do prompt quando o registro canônico mudar com frequência. Dê ao modelo uma função estreita, somente de leitura, como get_character, e deixe o aplicativo devolver esse registro. Limite o número de turnos: quatro rodadas sobre o mesmo pacote grande podem custar quatro leituras de entrada. Para uma auditoria fixa de duas cenas, colocar os fatos no prompt é mais simples e mais barato.

O grounding nativo de Search e Maps do Google são integrações separadas; esta rota de chat usa funções que o seu aplicativo executa. As receitas de chat mostram o ciclo de ferramentas completo.

Deixe um Agent preparar a chamada

Para auditorias de continuidade repetidas, peça ao seu Agent de programação que use o SpicyAPI Skill: «Leia google/gemini-3.1-pro-preview/chat e depois adapte o exemplo à minha entrada; mostre a requisição antes de executá-la.» A consulta pela CLI é spicyapi models get google/gemini-3.1-pro-preview/chat --json; a consulta por MCP é spicyapi_model_get com model: "google/gemini-3.1-pro-preview/chat". As chamadas de chat usam um cliente compatível ou a API de chat; os comandos de tarefas de mídia não geram respostas de chat.

Projetos com conteúdo adulto

Indexação de roteiros, auditorias de continuidade e notas de produção são um bom uso. Prosa explícita é menos confiável: a SpicyAPI não adiciona filtro de conteúdo a esta rota, mas o modelo pode recusar ou suavizar um pedido. Em nossos testes de setembro de 2026, o conteúdo escrito de nível L3 foi concluída por inteiro em 1 de 3 requisições, e a escrita de cenas íntimas em 4 de 9. Nos testes de cenas íntimas, o enquadramento de ficção dentro da requisição concluiu 3 de 3, um prompt de sistema sozinho 1 de 3 e os pedidos diretos 0 de 3. Um pedido de ficção dá a este fluxo de trabalho um ponto de partida melhor do que depender só da mensagem de sistema, mas escolha outro modelo se prosa explícita confiável for a entrega principal. A avaliação do Gemini 3.1 Pro traz o detalhe.

Falhas comuns

Use a página do modelo para ver as tarifas atuais e testar a rota no Playground. É um modelo em preview, então decida qual modelo assume caso ele mude antes de carregar tráfego de produção.