Cómo usar Gemini 3.8 Flash en EvoLink: guía de producción

Inicio rápido

curl https://direct.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "Return three rollout risks for an AI API migration."}
    ],
    "max_tokens": 500
  }'

Qué necesitas

• Una cuenta de EvoLink y una API key guardada en una variable de entorno, nunca subida al control de versiones.
• Un cliente capaz de hacer peticiones HTTPS con JSON, o un SDK compatible con OpenAI con un base_url personalizado.
• Un conjunto de evaluación pequeño y representativo, con reglas de aceptación medibles.
• Logging de ID del modelo, estado, latencia, uso de tokens, reintentos y aceptación a nivel de aplicación.
• Un modelo de fallback como Gemini 3.7 Flash durante el despliegue.

Gemini 3.8 Flash acepta entrada de texto, imagen, vídeo, audio y PDF, y devuelve texto. Google documenta un contexto de entrada de 1,048,576 tokens y hasta 65,536 tokens de salida. Trata esos límites como capacidad, no como un motivo para llenar cada petición.

Elige la superficie de API

EvoLink expone dos estilos de petición útiles para cargas de trabajo Gemini:

Ejemplo en Python compatible con OpenAI

Instala el paquete de OpenAI para Python y apúntalo a EvoLink:

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["EVOLINK_API_KEY"],
    base_url="https://direct.evolink.ai/v1",
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {
            "role": "system",
            "content": "Answer with concise, testable recommendations.",
        },
        {
            "role": "user",
            "content": "Review this deployment plan and identify missing rollback gates.",
        },
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

Mantén la primera petición sencilla. Confirma la autenticación, el acceso a la ruta, el parseo de la respuesta y los campos de uso antes de añadir herramientas, contexto largo o streaming.

Ejemplo de petición nativa de Gemini

curl "https://direct.evolink.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $EVOLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Create a five-step canary checklist for this API release."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 800,
      "thinkingConfig": {"thinkingLevel": "medium"}
    }
  }'

Niveles de thinking y reglas de migración

Al migrar un cliente Gemini antiguo, audita estos puntos:

Que una petición devuelva HTTP 200 no basta. Vuelve a validar la salida estructurada, los argumentos de herramientas, el estado multi-turno y el comportamiento ante rechazos después de la migración.

Entrada multimodal sin desperdiciar contexto

El modelo puede entender texto, imágenes, vídeo, audio y PDF, pero una ventana de 1M de tokens no hace útil cualquier payload grande. Construye el contexto de forma deliberada:

• Incluye las secciones del documento o los segmentos de medios necesarios para la decisión.
• Mantén las instrucciones de sistema estables, la guía del repositorio y los esquemas de herramientas en un prefijo consistente para que la caché tenga oportunidad de ayudar.
• Recupera la evidencia relevante antes de adjuntar un archivo completo.
• Fija un presupuesto de salida adecuado a la tarea; el máximo de 65,536 tokens es un techo.
• Registra por separado los tokens de input y los de lectura de caché para que el "contexto grande" no oculte gasto evitable.

Para documentos largos repetidos, compara el comportamiento de aciertos de caché con un prefijo de prompt estable. La tarifa introductoria de lectura de caché de Google es de $0.075 por millón de tokens hasta el 31 de diciembre de 2026, pero la facturación de EvoLink debe verificarse en tu cuenta en vivo.

Despliegue en producción en cinco etapas

1. Verifica el acceso y el precio

Crea una key de prueba restringida, confirma que el modelo aparece en las rutas disponibles de la cuenta, envía una petición pequeña y comprueba el registro de uso o de facturación resultante. Una página pública del modelo confirma la disponibilidad prevista, no la ruta de llamada específica de tu cuenta.

2. Valida el contrato de petición

Prueba primero las peticiones síncronas. Después prueba el streaming, la salida estructurada, las herramientas, el contexto largo y la entrada multimodal como casos separados. Así aíslas los fallos de protocolo de los fallos de calidad del modelo.

3. Repite un conjunto de evaluación fijo

Compara 3.8 Flash con la línea base actual al mismo nivel de thinking. Mide el éxito al primer intento, los entregables aceptados, los tokens de output y de thinking, los aciertos de caché, las tool calls válidas, la latencia, la corrección humana y la tasa de fallback.

4. Canary con tráfico observable

Empieza con un porcentaje pequeño o con una clase de carga de trabajo de bajo riesgo. Adjunta el ID del modelo elegido y la cohorte de evaluación a cada traza. Evita promocionar automáticamente basándote solo en el éxito HTTP agregado.

5. Promociona o revierte según umbrales escritos

Promociona solo si el modelo supera los umbrales de calidad, coste y latencia definidos de antemano. Revierte restaurando el valor de modelo anterior cuando los errores críticos, el coste por tarea aceptada o la latencia crucen su límite.

Gestión de errores que sí pertenece a producción

Usa reintentos acotados solo para fallos transitorios como límites de tasa, indisponibilidad upstream o timeouts de transporte. No reintentes sin cambios payloads malformados ni parámetros no soportados.

Comportamiento recomendado:

• Reintenta los fallos transitorios con backoff exponencial y jitter.
• Fija un número máximo de intentos y un plazo de extremo a extremo.
• Reutiliza una estrategia de idempotencia allí donde la aplicación pueda crear efectos secundarios.
• Registra los IDs de petición y los cuerpos de error saneados; nunca registres API keys ni prompts sensibles.
• Enruta a un fallback probado cuando se alcance el plazo o el umbral de errores.
• Trata los errores 400 repetidos como un problema de contrato que hay que corregir, no como un problema de capacidad que baste con esperar a que pase.

Checklist de observabilidad

Para cada petición, captura:

• funcionalidad de la aplicación y cohorte de evaluación;
• IDs de modelo solicitado y servido;
• protocolo y familia de endpoint;
• nivel de thinking y límite de salida;
• tokens de input, output, thinking y lectura de caché cuando se devuelvan;
• latencia, estado, clase de error y número de reintentos;
• validez de la tool call o resultado de la validación de esquema;
• aceptación de la aplicación, corrección del revisor y resultado del fallback.

Estos datos permiten que un gateway de API unificado respalde la selección de modelo en lugar de convertirse en un proxy opaco. Puedes mantener varias rutas Gemini detrás de un mismo cliente sabiendo cuál de ellas crea valor.

Errores habituales de configuración

• Enviar gemini-3-8-flash en lugar de gemini-3.8-flash como ID del modelo.
• Usar contents nativos de Gemini en el endpoint compatible con OpenAI.
• Depender de que minimal se degrade silenciosamente a low, combinar thinkingBudget con thinkingLevel, contar con controles de muestreo ignorados o terminar la conversación con el rol model.
• Llenar la ventana de contexto sin recuperación ni filtrado de relevancia.
• Asumir que la tarifa pública de Google es idéntica a la tarifa en vivo de tu cuenta de EvoLink.
• Declarar el éxito tras un único HTTP 200 sin comprobar la forma de la respuesta ni la facturación.
• Cambiar el modelo por defecto de producción sin una vía de fallback medida.

Preguntas frecuentes

¿Cuál es el ID del modelo Gemini 3.8 Flash?

¿Qué endpoint de EvoLink debo usar?

¿Puedo usar el SDK de OpenAI para Python?

¿Con qué nivel de thinking debería empezar?

¿Gemini 3.8 Flash admite imágenes, vídeo, audio y PDF?

Sí, como modalidades de entrada. Devuelve texto y no ofrece generación de imágenes, audio ni streaming en vivo.

¿Es 3.8 Flash más barato que 3.7 Flash?

No según la tarifa durante el periodo introductorio de Google: sus tarifas de input, output y lectura de caché coinciden. Google indica que 3.8 usa más tokens, así que compara el coste completo por tarea aceptada.

¿Cómo confirmo que mi integración está lista para producción?

Verifica una llamada exitosa y su registro de facturación, prueba cada característica del protocolo que uses, repite un conjunto de evaluación fijo, haz canary con tráfico real y conserva un rollback explícito.

¿Dónde puedo comparar todas las rutas Gemini?

Fuentes y notas de verificación

• Google: lanzamiento de Gemini 3.8 Flash
• Google AI for Developers: modelo Gemini 3.8 Flash
• Google AI for Developers: precios de la Gemini API
• Google Cloud: guía de Gemini 3.8 Flash
• EvoLink: quickstart de la API nativa de Gemini
• EvoLink: referencia de la API nativa de Gemini
• EvoLink: quickstart compatible con OpenAI para Gemini