Como usar a API Gemini Decisions

Para usar a API Gemini Decisions, obtenha uma chave no Google AI Studio, instale o google-genai 3.2 ou posterior e chame client.decisions.create() com o modelo gemini-decision-1, um input compartilhado e um mapa de questions tipadas (noul, choice ou score). Você recebe uma probabilidade calibrada e um confidence para cada pergunta, com zero tokens de saída.

Abaixo: cada passo em Python, JavaScript e REST, da sua primeira pergunta sim/não ao roteamento por confiança e a uma suíte de testes de CI.

O que é a API Gemini Decisions?

A API Gemini Decisions é um endpoint da API Gemini Developer (v1beta) que responde a perguntas de conjunto fechado em vez de gerar texto. Você envia uma única entrada multimodal e até 1.000 perguntas independentes. O modelo gemini-decision-1 pontua todas as opções em uma única passagem e retorna probabilidades calibradas nas quais seu código pode se basear diretamente.

A Google anunciou a API em 11 de novembro de 2026. A documentação oficial define três tipos de pergunta:

O preço é de US$ 0,10 por 1 milhão de tokens de entrada e US$ 0 na saída, de acordo com a página de preços da API Gemini. A entrada compartilhada é cobrada uma vez por requisição, não importa quantas perguntas você faça. Se você já leu nosso guia sobre como usar a API OpenAI Decisions, o formato parecerá familiar, mas os campos abaixo são próprios do Gemini.

Passo 1: Obtenha uma chave de API e instale o SDK

1. Abra o Google AI Studio e crie uma chave de API.
2. Exporte-a: export GEMINI_API_KEY="your-key".
3. Instale o SDK 3.2 ou posterior: pip install -U google-genai ou npm install @google/genai@latest.

Você pode testar perguntas sem código primeiro no Decisions Playground, que exporta código pronto para execução.

Camada gratuita, verificado em 12 de novembro de 2026: a página de limites de taxa lista 200 requisições por minuto, 50.000 tokens por minuto e 10.000 requisições por dia na camada gratuita. A entrada é gratuita nela, mas a página de preços marca os dados da camada gratuita como “Usados para melhorar nossos produtos: Sim”, então mantenha dados reais de clientes em uma camada paga. Para mais informações sobre as cotas gratuitas da Google, consulte nosso guia sobre a camada gratuita da API Gemini.

Passo 2: Faça sua primeira pergunta noul (sim/não)

Uma pergunta noul retorna a probabilidade de a resposta ser sim. Atenção à versão da API v1beta: o endpoint não está disponível em v1.

Python:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
    questions={
        "is_damaged": {
            "type": "noul",
            "instructions": "Did the item arrive damaged?",
        },
    },
)

answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")

JavaScript:

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "The blue mug I ordered on Monday arrived cracked on Wednesday.",
  questions: {
    is_damaged: { type: "noul", instructions: "Did the item arrive damaged?" },
  },
});

const answer = result.answers?.is_damaged;
if (answer?.type === "noul") console.log(answer.noul, answer.confidence);

REST:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "The blue mug I ordered on Monday arrived cracked on Wednesday.",
    "questions": {
      "is_damaged": { "type": "noul", "instructions": "Did the item arrive damaged?" }
    }
  }'

A documentação da Google mostra esta resposta (um exemplo da documentação, não uma execução nossa):

{
  "answers": { "is_damaged": { "type": "noul", "noul": 0.99, "confidence": 0.99 } },
  "usage": { "total_input_tokens": 100, "total_output_tokens": 0, "total_tokens": 100 }
}

Quando “sim” for ambíguo, adicione criteria com uma true_description e uma false_description. Uma regra para lembrar: os valores de noul sempre ficam entre 0,01 e 0,99, então um limiar acima de 0,99 nunca corresponde.

Passo 3: Adicione perguntas choice e score

Coloque perguntas independentes sobre a mesma entrada em uma única requisição. A entrada é cobrada uma vez; cada pergunta adiciona apenas seus próprios tokens.

result = client.decisions.create(
    model="gemini-decision-1",
    input="I was charged twice for my order and the export page crashes in Safari.",
    questions={
        "department": {
            "type": "choice",
            "instructions": "Which department should handle this request?",
            "criteria": {
                "billing": "Payments, invoices, and refunds.",
                "technical": "Problems using the product.",
                "shipping": "Delivery and tracking.",
                "other": "Anything outside these categories.",
            },
        },
        "severity": {
            "type": "score",
            "instructions": "How severe is this issue for the user?",
            "criteria": [
                "Cosmetic: appearance only, no lost functionality.",
                "Workaround available: a task fails, but another way works.",
                "Fully blocked: a task fails with no workaround.",
            ],
        },
    },
)

Três detalhes da documentação costumam pegar as pessoas de surpresa:

• As chaves de choice são ordenadas alfabeticamente antes da pontuação. Use other como opção genérica, e não none_of_the_above, que fica antes das opções reais na ordenação.
• Os critérios de score são uma lista, ordenada do menor para o maior e indexada a partir de 0. O score retornado é uma média ponderada por probabilidade, então pode ficar entre níveis (a documentação mostra 1.12).
• O modelo nunca vê as chaves das suas perguntas. Escreva a pergunta completa em instructions.

Para obter um nível discreto a partir de um score, pegue a entrada mais provável:

sev = result.answers["severity"]
level = max(sev.probabilities, key=sev.probabilities.get)
print(sev.legend[level])

Passo 4: Envie imagens, PDFs e áudio

input aceita uma string, um bloco de conteúdo ou uma lista de blocos, no mesmo formato de bloco da API Interactions. Os blocos suportados são text, image, audio, video e document (somente PDF).

import base64

with open("earcup.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")
with open("return-form.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode("utf-8")

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {"type": "text", "text": "Customer photo and form for return #8821.\n"},
        {"type": "image", "data": image_b64, "mime_type": "image/jpeg", "resolution": "low"},
        {"type": "document", "data": pdf_b64, "mime_type": "application/pdf"},
    ],
    questions={
        "visible_damage": {
            "type": "noul",
            "instructions": "Does the photo show physical damage to the device? Ignore the packaging.",
        },
        "form_signed": {
            "type": "noul",
            "instructions": "Is the return form in the PDF signed by the customer?",
        },
    },
)

Para áudio, passe um bloco como {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"}. Limites que vale a pena conhecer:

• Dados base64 inline têm limite de 100 MB por requisição (50 MB para PDFs); URLs externas têm limite de 15 MB cada.
• Defina o tipo MIME real. A API rejeita application/octet-stream.
• URLs do YouTube e URIs gs:// não são suportados. Use a API Files, uma URL HTTPS pública ou assinada, ou bytes inline.
• resolution (low, medium, high, ultra_high) troca detalhe visual por tokens. ultra_high é apenas para imagens.

Passo 5: Interprete as probabilidades e a confiança

Cada resposta traz um confidence de 0 a 1, a probabilidade estimada de que a principal resposta esteja correta. Para choice e score, ele equivale à probabilidade do resultado principal. Para noul, é max(noul, 1 - noul).

Assim, um noul de 0,03 tem uma confiança de 0,97: o modelo tem certeza de que a resposta é não.

Passo 6: Encaminhe respostas de baixa confiança para um fallback

Use o valor para escolher uma ação e a confiança para decidir se deve agir automaticamente:

a = result.answers
dept = a["department"]

if dept.confidence >= 0.7 and dept.choice != "other":
    route_to(dept.choice)
elif dept.confidence >= 0.4:
    route_to_fallback_model(ticket)   # a bigger model reasons it out
else:
    route_to("human_review")

Os cortes de 0,7 e 0,4 são exemplos: a Google recomenda definir os limiares a partir de exemplos rotulados do seu próprio tráfego. Mais duas regras da documentação:

• Perguntas choice sempre distribuem a probabilidade entre suas opções, mesmo quando nenhuma se encaixa. Combine-as com uma verificação de escopo, como “Esta mensagem é sobre um pedido?”
• Trate a entrada como não confiável. A mensagem de um usuário pode argumentar a favor de sua própria classificação. Mantenha um humano ou uma segunda verificação em pagamentos e outras ações de alto risco.

Passo 7: Deixe seu agente de código testá-la com o Apidog CLI

Uma camada de roteamento falha silenciosamente. Alguém reformula um critério, billing passa a virar technical para metade dos seus tickets, e nada dá erro. A solução é uma suíte de regressão que fixa as decisões esperadas, e seu agente de código pode construí-la com o Apidog CLI enquanto você revisa.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Depois, dê ao seu agente um único prompt:

In Apidog project <id>, build a test suite for POST
https://generativelanguage.googleapis.com/v1beta/decisions (header x-goog-api-key
from env var GEMINI_API_KEY). Add one request per question type (noul, choice,
score) asserting status 200, confidence between 0 and 1 and zero output tokens.
Add a test data set of 20 tickets with expected departments and assert each
choice matches with confidence >= 0.7. Run it and summarize failures.

O agente lê o esquema de cada payload, valida-o, escreve os recursos e executa a suíte:

apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file scenario.json
apidog test-data create --project <id> --file tickets.json
apidog test-suite create --project <id> --file suite.json
apidog run --test-suite <suiteId> --project <id> -e <envId> -d <testDataId> -r cli,junit --out-dir reports

Cada flag acima vem de apidog run --help na CLI 2.2.12. Agora, uma alteração de prompt ou de critérios que inverta a decisão de um fixture faz a execução falhar. Adicione o mesmo apidog run ... -r cli,junit ao GitHub Actions e o arquivo JUnit mostrará qual ticket mudou; nosso guia de CI/CD com Apidog CLI tem o arquivo de workflow, e Apidog CLI no Claude Code cobre a configuração do agente. O plano gratuito do Apidog cobre até 4 usuários.

Limites e o que ainda não é suportado

Conforme os limites da API Decisions, verificado em 12 de novembro de 2026:

• 1 a 1.000 perguntas por requisição, dentro de uma janela de contexto de 262.144 tokens.
• Sem cache de contexto, sem API Batch, sem inferência Flex ou Priority. Entradas repetidas entre requisições são cobradas integralmente.
• Bloqueios de segurança retornam HTTP 400 com um error.code como safety ou prohibited_content, e não uma resposta.
• Somente a API Gemini Developer (v1beta). A Google diz que o suporte ao Vertex AI está “chegando em breve”, sem data definida.

A Google informa uma latência ponta a ponta de 150 a 250 ms, quase constante de 1 a 100 perguntas para entradas de até 16 mil tokens, e afirma que o Gemini Decision 1 lidera sua própria suíte de benchmarks com o menor erro de calibração. Esses são números da Google; meça a latência nas suas próprias entradas antes de projetar com base neles.

FAQ

A API Gemini Decisions é gratuita? Há uma camada gratuita com entrada sem custo, limitada a 200 RPM, 50.000 TPM e 10.000 requisições por dia (verificado em 12 de novembro de 2026). Os dados da camada gratuita podem ser usados para melhorar os produtos da Google. A camada paga custa US$ 0,10 por 1 milhão de tokens de entrada.

O que significa noul? É o tipo de pergunta sim/não. O campo noul é a probabilidade de a resposta ser sim, entre 0,01 e 0,99.

Qual versão da API preciso usar? v1beta. Defina http_options={"api_version": "v1beta"} em Python, apiVersion: "v1beta" em JavaScript, ou chame /v1beta/decisions via REST.

Funciona no Vertex AI? Ainda não. Está disponível apenas na API Gemini Developer; a Google lista o Gemini no Google Cloud como em breve.

Como escolher um limiar de confiança? Rotule algumas centenas de entradas reais, execute-as pela API e escolha o ponto de corte em que o custo de ações automáticas erradas equivale ao custo da revisão humana.