KovAPIKovAPI
POST https://kovapi.com/v1/chat/completions

Gemini 4 Hydrogen Beta admite conversación de texto, streaming y tres niveles de razonamiento Low / Medium / High (Low por defecto), además de entrada de imágenes, llamadas a funciones y salida JSON estructurada. Compatible con el SDK de OpenAI. El razonamiento se cobra como salida.

📥 Ventana de contexto (entrada máxima):Ventana oficial: 1.048.576 tokens compartidos por entrada y salida. Divide las tareas muy largas durante la Beta.

Probar en el Playground →

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
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-hydrogen", "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}]}'

Respuesta (HTTP 200)

JSON
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-4-hydrogen",
  "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.",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}

message.content es la respuesta y message.reasoning_content, el razonamiento. usage recoge los tokens que se cobran en esta petición: los tokens de razonamiento forman parte de completion_tokens y se cobran al precio de salida.

Paso 2 · Recibe la respuesta en streaming (recomendado)

curl
curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-hydrogen", "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)

Python
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-4-hydrogen",
    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-4-hydrogen",
    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

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

De un vistazo

Ventana de contexto~1 000 000 tokens
EntradaTexto, imágenes
RazonamientoElige low / medium / high; predeterminado: low. Todos usan las mismas tarifas por token.
Llamadas a herramientasSí (formato tools de OpenAI)
Salida JSONSí (response_format)
Búsqueda webSí (web_search: true; la búsqueda en sí es gratis)
Endpoints/v1/chat/completions
StreamingSí (stream: true, SSE)
Forma de cobroPor token: entrada, salida (razonamiento incluido) y aciertos de caché tienen cada uno su precio; los fallos no se cobran

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:

ParámetroTipoObligatorioDescripción
modelstringSíEl ID del modelo: gemini-4-hydrogen.
messagesarraySíLa conversación: cada mensaje tiene un role (system, user, assistant o tool) y un content. content es una cadena o un array de partes text e image_url (entrada de imágenes; ver más abajo). En conversaciones de varios turnos, envía todo el historial en orden.
streambooleanNoCon true, la respuesta llega en streaming como SSE, con usage en el último fragmento. Por defecto es false.
max_tokensintegerNoLongitud de salida solicitada, incluido el razonamiento. Para controlar el coste, limita también la extensión en el prompt.
temperature / top_pnumberNoParámetros de muestreo; se pasan al modelo tal cual (temperature va de 0 a 2). Puede que los modelos de razonamiento no los respeten.
reasoning_effortstringNoElige low / medium / high; predeterminado: low. Todos usan las mismas tarifas.
tools / tool_choicearray / stringNoLlamadas a funciones en el formato estándar de OpenAI. Cuando el modelo llama a una función, devuelve finish_reason: "tool_calls" con tool_calls; ver más abajo.
response_formatobjectNo{"type": "json_object"} hace que el modelo devuelva solo JSON válido; indica también en el prompt que quieres JSON y qué campos debe tener.
web_searchbooleanNoCon true, primero se hace una búsqueda web y los resultados se entregan al modelo como referencia; ver más abajo.

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.

TipoUSD / 1M de tokensCréditos / 1M de tokens
Entrada$0.4590
Salida (razonamiento incluido)$2.25450
Acierto de caché$0.02254.5

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

Razonamiento

Usa reasoning_effort con low, medium o high; si se omite, se usa low.

usage.completion_tokens incluye razonamiento y respuesta; no sumes el razonamiento una segunda vez.

Las tarifas son iguales en los tres niveles. Un esfuerzo mayor consume más tokens de salida.

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

JSON · reasoning_effort
{
  "model": "gemini-4-hydrogen",
  "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}],
  "reasoning_effort": "medium"
}

Caché de prompts

Se admite caché implícita automática. Las entradas largas repetidas pueden acertar; los aciertos reales cuestan una vigésima parte de la entrada normal. Repetir no garantiza un acierto y no se ofrece creación de caché explícita.

usage.prompt_tokens es la entrada total. usage.prompt_tokens_details.cached_tokens es la parte de ese total servida desde caché. Solo los aciertos reales usan la tarifa de caché.

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

Llamadas a herramientas (function calling)

Describe tus funciones en tools con JSON Schema. Cuando el modelo decide llamar a una, devuelve finish_reason: "tool_calls" con el nombre de la función y los argumentos (una cadena JSON) en message.tool_calls.

curl
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-4-hydrogen", "messages": [{"role": "user", "content": "¿Qué tiempo hace ahora en Shanghái?"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'

Ejecuta la función, añade el resultado como un mensaje role: "tool" con el tool_call_id correspondiente y vuelve a enviar la conversación; entonces el modelo dará su respuesta final. tool_choice acepta auto, none, required o una función concreta.

Límites de la Beta

  • Se verificaron texto, streaming, tres niveles de razonamiento, entrada de imágenes, llamadas a funciones y salida JSON estructurada.
  • El contexto oficial es de aproximadamente un millón de tokens, compartido por entrada y salida; divide las tareas muy largas.
  • Las solicitudes fallidas no se cobran; las interrumpidas que produjeron salida se liquidan por uso real.

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.

HTTPcodeCausaQué hacer
400invalid_messages / invalid_role / invalid_max_tokensEn una petición de chat, messages falta, está vacío o tiene un formato incorrecto, un role no es uno de los valores permitidos, o max_tokens no es un entero positivo. param indica el campo.Corrige el campo que indica param.
400model_not_foundEl ID del modelo está mal escrito, falta model, o el modelo no se puede usar en este endpoint (por ejemplo, un modelo de chat en el endpoint de imágenes).Usa un ID de modelo de GET /v1/models o de la referencia de la API.
400max_tokens_too_smallUn modelo de razonamiento gastó todo max_tokens en razonar y no escribió ninguna respuesta (chat sin streaming).Sube max_tokens y reintenta.
4xxinvalid_requestEl proveedor del modelo rechazó la petición (por ejemplo, por un contexto demasiado largo o un parámetro no admitido); el estado y message se transmiten tal como los envió el proveedor, y code es el valor del proveedor.Modifica la petición según lo que indique message.
401invalid_api_keyLa clave no existe, se eliminó o está desactivada, o la cuenta está desactivada.Revisa la clave en la página API Keys de la consola.
402insufficient_quotaNo hay saldo suficiente para retener el importe de esta petición. La pasarela retiene primero el coste máximo posible de la petición, así que una ráfaga de llamadas simultáneas también puede provocarlo.Si se debe a una ráfaga, espera unos segundos y reintenta; si no, recarga.
403permission_deniedEl modelo no está en la lista de modelos permitidos de la clave.Usa un modelo de la lista o edita la lista en la consola.
429rate_limit_exceededSe superó el límite de peticiones por minuto configurado en esta clave (contado sobre los últimos 60 segundos). Sin cabecera Retry-After.Espera unos segundos y reintenta, o sube el límite de la clave en la consola.
429rate_limit_exceededEl modelo está al límite de su capacidad y la petición no se envió. Solo en los endpoints de chat: los trabajos de imagen y vídeo nunca se rechazan, sino que esperan en cola. Los endpoints compatibles con OpenAI añaden Retry-After.Espera los segundos que indica Retry-After y reintenta.
502upstream_timeoutEl proveedor agotó el tiempo de espera, incluido el caso de tardar demasiado en enviar el primer token.Reintenta; para respuestas largas, usa stream: true.
502upstream_unavailableEl proveedor falló o no está disponible por el momento.Reintenta en breve.
502upstream_busyEl proveedor del modelo está limitando las peticiones. Un 429 del proveedor nunca te llega como 429; en su lugar recibes este 502.Reintenta en breve.
502empty_completionEl proveedor del modelo devolvió un contenido vacío. No es una valoración de tu contenido.Reintenta.
503model_maintenanceEl modelo está en mantenimiento y no acepta peticiones; mientras tanto, ningún otro modelo responde en su lugar.Reintenta cuando termine el mantenimiento; consulta el estado del servicio.

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.