Cómo usar la API de Gemini Decisions

Para usar la Gemini Decisions API, consigue una clave en Google AI Studio, instala google-genai 3.2 o posterior y llama a client.decisions.create() con el modelo gemini-decision-1, un único input compartido y un mapa de questions tipadas (noul, choice o score). Recibirás una probabilidad calibrada y un confidence para cada pregunta, con cero tokens de salida.

A continuación: cada paso en Python, JavaScript y REST, desde tu primera pregunta sí/no hasta el enrutamiento por confianza y una suite de pruebas para CI.

¿Qué es la Gemini Decisions API?

La Gemini Decisions API es un endpoint de la Gemini Developer API (v1beta) que responde preguntas de conjunto cerrado en lugar de generar texto. Envías una única entrada multimodal y hasta 1.000 preguntas independientes. El modelo gemini-decision-1 puntúa cada opción en una sola pasada hacia adelante y devuelve probabilidades calibradas sobre las que tu código puede ramificar directamente.

Google lo anunció el 11 de noviembre de 2026. La documentación oficial define tres tipos de preguntas:

El precio es de 0,10 $ por cada 1 M de tokens de entrada y 0 $ por la salida, según la página de precios de la Gemini API. La entrada compartida se factura una sola vez por petición, sin importar cuántas preguntas hagas. Si ya has leído nuestra guía sobre cómo usar la OpenAI Decisions API, la forma te resultará familiar, pero los campos siguientes son propios de Gemini.

Paso 1: Consigue una clave de API e instala el SDK

1. Abre Google AI Studio y crea una clave de API.
2. Expórtala: export GEMINI_API_KEY="tu-clave".
3. Instala el SDK 3.2 o posterior: pip install -U google-genai o npm install @google/genai@latest.

Puedes probar preguntas sin escribir código primero en el Decisions Playground, que exporta código listo para ejecutar.

Nivel gratuito, verificado el 12 de noviembre de 2026: la página de límites de tasa indica 200 peticiones por minuto, 50.000 tokens por minuto y 10.000 peticiones al día en el nivel gratuito. La entrada es gratuita ahí, pero la página de precios marca los datos del nivel gratuito como «Used to improve our products: Yes», así que guarda los datos reales de clientes en un nivel de pago. Para más información sobre las cuotas gratuitas de Google, consulta nuestra guía del nivel gratuito de la Gemini API.

Paso 2: Haz tu primera pregunta noul (sí/no)

Una pregunta noul devuelve la probabilidad de que la respuesta sea sí. Fíjate en la versión de la API v1beta: el endpoint no está en 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?" }
    }
  }'

La documentación de Google muestra esta respuesta (un ejemplo de los docs, no una ejecución nuestra):

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

Cuando «sí» sea ambiguo, añade criteria con una true_description y una false_description. Una regla que recordar: los valores de noul siempre están entre 0.01 y 0.99, así que un umbral por encima de 0.99 nunca coincidirá.

Paso 3: Añade preguntas de tipo choice y score

Coloca preguntas independientes sobre la misma entrada en una sola petición. La entrada se factura una vez; cada pregunta solo añade sus propios 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.",
            ],
        },
    },
)

Tres detalles de la documentación que confunden a la gente:

• Las claves de choice se ordenan alfabéticamente antes de puntuar. Usa other como comodín, no none_of_the_above, que se ordena antes que las opciones reales.
• Los criterios de score son una lista, ordenada de menor a mayor e indexada desde 0. El score devuelto es un promedio ponderado por probabilidad, por lo que puede caer entre niveles (los docs muestran 1.12).
• El modelo nunca ve las claves de tus preguntas. Escribe la pregunta completa en instructions.

Para obtener un nivel discreto a partir de un score, toma la entrada más probable:

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

Paso 4: Envía imágenes, PDF y audio

input acepta una cadena, un bloque de contenido o una lista de bloques, con el mismo formato de bloque que la Interactions API. Los bloques admitidos son text, image, audio, video y document (solo 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 audio, pasa un bloque como {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"}. Límites que conviene conocer:

• Los datos base64 en línea están limitados a 100 MB por petición (50 MB para PDF); las URL externas, a 15 MB cada una.
• Indica el tipo MIME real. La API rechaza application/octet-stream.
• No se admiten URL de YouTube ni URIs gs://. Usa la Files API, una URL HTTPS pública o firmada, o bytes en línea.
• resolution (low, medium, high, ultra_high) intercambia detalle visual por tokens. ultra_high es solo para imágenes.

Paso 5: Lee las probabilidades y la confianza

Cada respuesta incluye un confidence de 0 a 1, la probabilidad estimada de que la respuesta principal sea correcta. Para choice y score, coincide con la probabilidad del resultado principal. Para noul, es max(noul, 1 - noul).

Así, un noul de 0.03 tiene una confianza de 0.97: el modelo está seguro de que la respuesta es no.

Paso 6: Envía las respuestas de baja confianza a un fallback

Usa el valor para elegir una acción y la confianza para decidir si actuar de forma automática:

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")

Los cortes de 0.7 y 0.4 son marcadores de posición: Google recomienda fijar los umbrales a partir de ejemplos etiquetados de tu propio tráfico. Dos reglas más de la documentación:

• Las preguntas choice siempre reparten la probabilidad entre tus opciones, incluso cuando ninguna encaja. Combínalas con una comprobación de alcance como «¿Este mensaje trata sobre un pedido?».
• Trata la entrada como no confiable. El mensaje de un usuario puede argumentar a favor de su propia clasificación. Mantén una revisión humana o una segunda comprobación en pagos y otras acciones de alto riesgo.

Paso 7: Deja que tu agente de código lo pruebe con Apidog CLI

Una capa de enrutamiento falla en silencio. Alguien reformula un criterio, billing pasa a ser technical para la mitad de tus tickets y nada da error. La solución es una suite de regresión que fije las decisiones esperadas, y tu agente de código puede construirla con Apidog CLI mientras tú supervisas.

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

Luego dale a tu agente un ú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.

El agente lee el esquema de cada payload, lo valida, escribe los recursos y ejecuta la suite:

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 anterior proviene de apidog run --help en la CLI 2.2.12. Ahora, cualquier cambio de prompt o de criterios que altere la decisión de un fixture hará fallar la ejecución. Integra el mismo apidog run ... -r cli,junit en GitHub Actions y el archivo JUnit mostrará qué ticket cambió; nuestra guía de CI/CD con Apidog CLI incluye el archivo de workflow, y Apidog CLI en Claude Code cubre la configuración del agente. El plan gratuito de Apidog cubre hasta 4 usuarios.

Límites y qué aún no está soportado

Según los límites de la Decisions API, verificados el 12 de noviembre de 2026:

• De 1 a 1.000 preguntas por petición, dentro de una ventana de contexto de 262.144 tokens.
• Sin context caching, sin Batch API, sin inferencia Flex ni Priority. La entrada repetida entre peticiones se factura por completo.
• Los bloqueos de seguridad devuelven HTTP 400 con un error.code como safety o prohibited_content, no una respuesta.
• Solo en la Gemini Developer API (v1beta). Google dice que el soporte de Vertex AI llegará «pronto», sin fecha.

Google reporta una latencia de extremo a extremo de 150 a 250 ms, casi plana de 1 a 100 preguntas para entradas de hasta 16K tokens, y afirma que Gemini Decision 1 lidera su propia suite de benchmarks con el menor error de calibración. Esos son los números de Google; mide la latencia con tus propias entradas antes de diseñar en torno a ellos.

FAQ

¿La Gemini Decisions API es gratuita? Hay un nivel gratuito con entrada sin costo, con un máximo de 200 RPM, 50.000 TPM y 10.000 peticiones al día (verificado el 12 de noviembre de 2026). Los datos del nivel gratuito pueden usarse para mejorar los productos de Google. El nivel de pago cuesta 0,10 $ por cada 1 M de tokens de entrada.

¿Qué significa noul? Es el tipo de pregunta sí/no. El campo noul es la probabilidad de que la respuesta sea sí, entre 0.01 y 0.99.

¿Qué versión de la API necesito? v1beta. Establece http_options={"api_version": "v1beta"} en Python, apiVersion: "v1beta" en JavaScript, o llama a /v1beta/decisions por REST.

¿Funciona en Vertex AI? Todavía no. Está solo en la Gemini Developer API; Google indica que Gemini en Google Cloud llegará pronto.

¿Cómo elijo un umbral de confianza? Etiqueta unos cientos de entradas reales, pásalas por la API y elige el punto de corte donde el costo de las acciones automáticas equivocadas iguale el costo de la revisión humana.