Gemini 3.1 Pro · API

Inicio rápido

Dos pasos: envía una petición y luego recibe la respuesta en streaming. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual. El endpoint sigue el formato Chat Completions de OpenAI, así que al código de OpenAI que ya tengas solo hay que cambiarle base_url y model.

Paso 1 · Envía una petición

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}]}'

Respuesta (HTTP 200)

{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-3.1-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "La fotosíntesis es el proceso por el que las plantas usan la luz solar para transformar el dióxido de carbono y el agua en azúcar y liberar oxígeno."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60,
    "prompt_tokens_details": {"cached_tokens": 0}
  }
}

message.content es la respuesta. usage recoge los tokens que se cobran en esta petición; prompt_tokens_details.cached_tokens es la parte servida desde la caché, que se cobra al precio de caché.

Paso 2 · Recibe la respuesta en streaming (recomendado)

curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "stream": true, "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}]}'

El streaming es SSE estándar: cada fragmento lleva texto en choices[0].delta.content, el último fragmento lleva usage y al final llega data: [DONE]. Usa streaming con respuestas largas y con modelos de razonamiento: una petición sin streaming se corta pasados unos 10 minutos.

Python (SDK de OpenAI)

from openai import OpenAI

client = OpenAI(base_url="https://kovapi.com/v1", api_key="YOUR_API_KEY")

# 1. Una petición, una respuesta
resp = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "Explica la fotosíntesis en una frase"}],
)
print(resp.choices[0].message.content)

# 2. En streaming
stream = client.chat.completions.create(
    model="gemini-3.1-pro",
    messages=[{"role": "user", "content": "Explica la fotosíntesis en una frase"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

De un vistazo

Parámetros de la petición

El cuerpo JSON de POST /v1/chat/completions, igual que en la API Chat Completions de OpenAI. Estos son los parámetros habituales y lo que hace cada uno en este modelo:

Los demás parámetros de OpenAI (como stop, seed o user) se pasan al modelo tal cual; que tengan efecto o no depende del modelo.

Precio

Se cobra por token, a las tarifas vigentes de la tabla de abajo (por millón de tokens). Solo se cobran las peticiones que salen bien, según el uso real: los fallos, los tiempos de espera agotados y los rechazos no se cobran. 1 crédito = $0.005.

Por ejemplo, una petición con 2 000 tokens de entrada y 1 000 tokens de salida (razonamiento incluido) cuesta aproximadamente $0.004.

Razonamiento

Dos niveles: sin indicar el esfuerzo, o con reasoning_effort: "low", se usa el nivel estándar, más rápido y con menos tokens de razonamiento; con medium, high o xhigh, el nivel de razonamiento alto, que razona más a fondo y se cobra a su propio precio (consulta la sección de precio más arriba); las peticiones del nivel de razonamiento alto figuran como gemini-3.1-pro-preview en la facturación y en el registro de llamadas.

El nivel también se puede elegir con el ID del modelo: gemini-3.1-pro-high para el nivel de razonamiento alto y gemini-3.1-pro-low para el nivel estándar.

Los tokens de razonamiento forman parte de usage.completion_tokens y se cobran al precio de salida (algunos modelos los desglosan además en completion_tokens_details.reasoning_tokens).

Caché de prompts

No hace falta ningún parámetro: el proveedor del modelo puede guardar en caché automáticamente un prefijo largo que se repite (el mismo prompt de sistema, los turnos anteriores de una conversación), y la parte en caché se cobra al precio de caché, más bajo. Si se guarda en caché y cuánto lo decide el proveedor; pon al principio de los mensajes lo que nunca cambia para conseguir más aciertos.

El número de tokens en caché llega en usage.prompt_tokens_details.cached_tokens; esa parte se cobra al precio de acierto de caché y el resto de la entrada, al precio de entrada.

Entrada de imágenes

Pon una parte image_url en el array content. Lo recomendado es un data URI en base64 (data:image/png;base64,...), que siempre se puede leer; un enlace público a una imagen hay que descargarlo primero, y de vez en cuando no se consigue o agota el tiempo de espera. Las imágenes cuentan como tokens de entrada según las reglas del fabricante del modelo.

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "messages": [{"role": "user", "content": [{"type": "text", "text": "¿Qué hay en esta imagen?"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'

Búsqueda web

Añade "web_search": true a la petición (o una entrada {"type": "web_search"} en tools): la pasarela primero busca en la web en tiempo real según la conversación, entrega al modelo hasta 5 resultados con sus enlaces como referencia, y el modelo responde citando sus fuentes. La búsqueda en sí es gratis; el texto de referencia se cobra como tokens de entrada.

curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro", "web_search": true, "messages": [{"role": "user", "content": "¿Cuáles son las noticias de tecnología más importantes de hoy?"}]}'

Fiabilidad y reintentos automáticos

• Si una petición da error, agota el tiempo de espera o choca con el límite de capacidad, la pasarela la reintenta automáticamente antes de devolver nada, así que no tienes que reintentar y nunca se cobra dos veces.
• Cuando un streaming empieza a enviar datos, ya no se reintenta automáticamente: si se corta a medias, se cobra el uso generado hasta ese momento (consulta Facturación y reembolsos).
• Cuando el modelo está al límite de su capacidad, la pasarela devuelve 429 con Retry-After: espera esos segundos y reintenta. Las peticiones fallidas no se cobran. El estado de cada modelo aparece en la página de estado.

Errores y reembolsos

Los errores llegan como un objeto error (message, type, code, param); decide según el estado HTTP y code, nunca comparando el texto de message. Las peticiones fallidas no se cobran; la lista completa está en Códigos de error.

Si un streaming falla después de empezar a enviar datos, el código de estado no cambia: el error llega como una línea de datos con error, o el streaming simplemente termina (sin data: [DONE]). Trátalo como interrumpido.