# Documentación para desarrolladores de la API de KovAPI

Pasarela de API de IA compatible con OpenAI. Base URL: `https://kovapi.com/v1`

## Autenticación
Toda petición lleva un Bearer token:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Modelos y precios
| Modelo | Capacidad | Endpoint | Precio |
| --- | --- | --- | --- |
| gpt-5.6-sol | Razonamiento de frontera, programación agéntica, tareas de largo recorrido, salida estructurada | /chat/completions | entrada $1.2/1M · salida $6.0/1M |
| gpt-5.6-luna | Chat a alta velocidad, programación agéntica, gran volumen con baja latencia, salida estructurada | /chat/completions | entrada $0.07/1M · salida $0.4/1M |
| gpt-6-astra | Razonamiento profundo, programación agéntica, contexto muy largo, entrada de imagen, salida estructurada | /chat/completions | entrada $3.0/1M · salida $15.0/1M |
| gpt-6.1-sol | Programación agéntica, programación compleja, documentos y análisis profesionales, razonamiento, contexto muy largo, entrada de imagen, salida estructurada | /chat/completions | entrada $0.6/1M · salida $3.0/1M |
| gpt-6-sol | Programación compleja, flujos agénticos, razonamiento, contexto muy largo, entrada de imagen, salida estructurada | /chat/completions | entrada $0.6/1M · salida $3.0/1M |
| gpt-6-luna | Chat de gran volumen, pasos de agente de baja latencia, clasificación y extracción, contexto muy largo, salida estructurada | /chat/completions | entrada $0.07/1M · salida $0.4/1M |
| gpt-image-2 | Texto a imagen, imagen a imagen, portadas, carteles, ilustraciones | /images/generations | 1K $0.005 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-flare | Texto a imagen, imagen a imagen, portadas, carteles, ilustración, tipografía | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| gpt-image-2.5-sunburst | Texto a imagen, imagen a imagen, portadas, carteles, ilustración, tipografía | /images/generations | 1K $0.005 · 2K $0.03 · 4K $0.05 |
| nano-banana-2 | Texto a imagen, imagen a imagen, portadas, carteles, ilustraciones | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-pro | Texto a imagen, imagen a imagen, portadas, carteles, ilustraciones, infografías | /images/generations | 1K $0.02 · 2K $0.03 · 4K $0.05 |
| nano-banana-2.1 | Texto a imagen, edición de imágenes, composición con varias imágenes, pósteres e infografías, fotos de producto, banners panorámicos | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| grok-imagine-image | Texto a imagen, edición de imágenes, carteles, fotos de producto, imágenes para redes, rótulos en chino e inglés | /images/generations | 1K $0.005 · 2K $0.005 |
| grok-imagine-image-quality | Portadas, carteles, fotos de producto, ilustración, texto a imagen y edición | /images/generations | 1K $0.01 · 2K $0.01 |
| claude-sonnet-4-6 | Chat, código, razonamiento, contexto largo | /chat/completions | entrada $1.5/1M · salida $7.5/1M |
| claude-opus-5 | Razonamiento profundo, código, agentes, contexto largo, comprensión de imágenes | /chat/completions | entrada $4.0/1M · salida $20.0/1M |
| claude-fable-5 | Escritura en chino, creación narrativa, textos largos, chat, código, comprensión de imágenes | /chat/completions | entrada $8.0/1M · salida $40.0/1M |
| claude-opus-5-5 | Razonamiento complejo, programación agéntica de largo recorrido, ingeniería de software, llamadas a herramientas, comprensión de imágenes y PDF | /chat/completions | entrada $2.5/1M · salida $12.5/1M |
| claude-sonnet-5-5 | Programación y agentes del día a día, contexto largo, llamadas a herramientas, comprensión de imágenes y PDF, tráfico de producción a escala | /chat/completions | entrada $1.5/1M · salida $7.5/1M |
| gemini-4-argon | Beta · razonamiento · contexto largo | /chat/completions | entrada $0.5/1M · salida $3.0/1M |
| gemini-3.1-pro | Chat, razonamiento, contexto muy largo, multimodal | /chat/completions | entrada $0.5/1M · salida $3.0/1M |
| gemini-3.8-flash | Chat, razonamiento, razonamiento adaptativo, entrada de imagen, contexto muy largo | /chat/completions | entrada $0.6/1M · salida $3.6/1M |
| deepseek-v4.1-flash | Chat, razonamiento, programación, llamadas a herramientas, modo de razonamiento activable | /chat/completions | entrada $0.075/1M · salida $0.3/1M |
| deepseek-v4-flash-0731 | Chat, razonamiento, programación, llamadas a herramientas, modo de razonamiento activable, versión fija | /chat/completions | entrada $0.13/1M · salida $0.51/1M |
| glm-5.3 | Chat, programación, flujos de agentes, razonamiento, redacción en chino e inglés, llamadas a herramientas | /chat/completions | entrada $1.12/1M · salida $3.52/1M |
| qwen3.8-max | Razonamiento, programación, agentes y llamadas a herramientas, redacción en chino e inglés, comprensión de imágenes | /chat/completions | entrada $1.4/1M · salida $4.2/1M |
| qwen3.8-flash | Chat de gran volumen, clasificación y extracción, resumen y reescritura, comprensión de imágenes y OCR, llamadas a herramientas | /chat/completions | entrada $0.1/1M · salida $0.33/1M |
| grok-4.7 | Razonamiento complejo, programación, análisis de documentos largos, llamadas a herramientas, salida estructurada, comprensión de imágenes | /chat/completions | entrada $0.3/1M · salida $0.9/1M |
| veo-3.1 | Clips cortos, movimiento de producto, transiciones entre fotogramas, material comercial | /videos/generations | $0.2 / clip |
| gemini-omni-flash | Clips de varios planos, narración por guion, transiciones entre fotogramas | /videos/generations | $0.05 / s (6-10 s, facturado por segundo) |
| seedance-2.5-token | Referencias de texto, imagen, vídeo y audio | /videos/generations | USD / 1M video tokens: 480p/720p $10.2 ($6.1 with reference video); 1080p $11.1 ($6.7 with reference video). |
| seedance-2.5-token-draft | Referencias de texto, imagen, vídeo y audio | /videos/generations | USD / 1M video tokens: 480p draft $10.2 ($6.1 with reference video). Upgrade billed separately. |
| seedance-2.5 | Cortos de plano largo, entrada con varias referencias, material comercial | /videos/generations | $0.158 / s (4-30 s, facturado por segundo) |
| seedance-2.0 | Clips cortos, material comercial | /videos/generations | $0.15 / s (5-15 s, facturado por segundo) |
| seedance-2.0-fast | Material en lote, validación rápida de ideas | /videos/generations | $0.075 / s (5-15 s, facturado por segundo) |
| seedance-2.0-mini | Borradores en volumen, iteración de bajo coste | /videos/generations | $0.046 / s (5-15 s, facturado por segundo) |
| seedance-2.0-clip | Clips cortos con personas reales, vídeos de producto, producción en lote | /videos/generations | $1.0 / clip |
| seedance-2.5-30s | Narrativa en plano largo, vídeos de producto de formato largo | /videos/generations | $2.0 / clip |
| wan3.0-video | Narrativa de plano largo, composición con varios materiales, reescritura de vídeo | /videos/generations | $0.065 / s (4-30 s, facturado por segundo) |
| wan3.0-video-prime | Material con plazo ajustado, pruebas de plano en lote | /videos/generations | $0.112 / s (4-30 s, facturado por segundo) |
| minimax-h3 | Metraje en alta definición, clips cortos con sonido | /videos/generations | $0.036 / s (5-15 s, facturado por segundo) |
| grok-imagine-video-1.5 | Vídeos cortos en volumen, comprobación rápida de ideas | /videos/generations | $0.3 / clip |

## Chat (Chat Completions)
`POST /v1/chat/completions`, con `stream: true` para salida en streaming.
```bash
curl https://kovapi.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'
```
Entrada de imagen (visión): pon un `image_url` en el array `content` de `messages`, con un enlace público a la imagen o un data URL en base64:
```bash
curl https://kovapi.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"gpt-5.5","messages":[{"role":"user","content":[{"type":"text","text":"¿Qué hay en esta imagen?"},{"type":"image_url","image_url":{"url":"https://example.com/photo.jpg"}}]}]}'
```

## Imágenes — trabajos asíncronos (al enviar recibes un id de trabajo)
Los endpoints de imagen funcionan **solo por trabajos**: al enviar recibes al instante `HTTP 202` y un `id` de trabajo (`{"id":"img_...","object":"image.generation.job","status":"queued"}`); consulta `GET /v1/images/jobs/{id}` hasta que `status` sea `succeeded` y lee `data[0].url` (un enlace de `img.kovapi.com` que se conserva 15 días; descárgalo o cópialo a tu propio almacenamiento). **No** esperes recibir `data` en la respuesta del envío.
**Texto a imagen** es `POST /v1/images/generations`. **Imagen a imagen** es `POST /v1/images/edits`, o añade `image` a generations: las dos formas son equivalentes; `image` acepta una URL pública, un `data:` URI o base64.
```bash
# 1) enviar -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"gpt-image-2","prompt":"a poster","size":"2:3"}'
# 2) consultar cada 2-3 s hasta status=succeeded; el resultado está en data[0].url
curl https://kovapi.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
En `size`, pasa una relación de aspecto (`1:1` / `3:4` / `2:3` / `9:16` / `4:3` / `3:2` / `16:9`) y el modelo renderiza de forma **nativa** con esa proporción, sin recortar el sujeto; también se aceptan tamaños en píxeles (`1024x1024` / `1024x1536` / `1536x1024`). Funciona tanto en texto a imagen como en imagen a imagen. El campo `async` ya no hace falta y se ignora si lo envías.


## Vídeo — trabajos asíncronos (al enviar recibes un id de trabajo)
El vídeo también es un trabajo: `POST /v1/videos/generations` devuelve al instante `HTTP 202` y un id de trabajo (`{"id":"img_...","object":"video.generation.job","status":"queued"}`); consulta `GET /v1/videos/jobs/{id}` hasta que `status` sea `succeeded` y lee `data[0].url` (un enlace mp4 rehospedado que se conserva 15 días). Un clip tarda de uno a varios minutos (los largos, más). La mayoría de los modelos factura por segundo de vídeo y unos pocos por clip (la tabla de arriba da cada tarifa); si el trabajo falla se reembolsa íntegramente. `size` fija la relación de aspecto (`16:9` horizontal por defecto, `9:16` vertical); para imagen a vídeo pasa una referencia de primer fotograma en `image`.
```bash
# 1) enviar -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"veo-3.1","prompt":"un gato surfeando al atardecer","size":"16:9","duration":"8s"}'
# 2) consultar cada 5 s hasta status=succeeded; el resultado está en data[0].url
curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
Modelos de vídeo disponibles: `veo-3.1`, `gemini-omni-flash`, `seedance-2.5-token`, `seedance-2.5-token-draft`, `seedance-2.5`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `seedance-2.0-clip`, `seedance-2.5-30s`, `wan3.0-video`, `wan3.0-video-prime`, `minimax-h3`, `grok-imagine-video-1.5`.
Parámetros comunes: `size` (o `aspect_ratio`) fija la orientación, `duration` la duración, `resolution` la calidad (solo en los modelos que la admiten), y `image` / `images[]` aporta una imagen de referencia, lo que lo convierte en imagen a vídeo. Las duraciones y resoluciones admitidas cambian según el modelo; la tabla exacta de cada uno está en `/docs/<id del modelo>`, por ejemplo [/docs/veo-3.1](/veo-3.1).

## API nativa de Anthropic (Claude Code se conecta directamente)
Además de la ruta compatible con OpenAI, los modelos Claude se ofrecen también por la **API nativa de mensajes de Anthropic**. Apunta `ANTHROPIC_BASE_URL` en Claude Code (o en cualquier SDK de Anthropic) a `https://kovapi.com/anthropic` y usa tu clave de la pasarela como `x-api-key` (`Authorization: Bearer` también funciona). El razonamiento, el uso de herramientas y la caché de prompts pasan todos sin cambios. Modelos: claude-opus-5, claude-fable-5, claude-sonnet-4-6. Se factura exactamente igual que /v1, por token, incluidas las lecturas y escrituras de caché.
```bash
export ANTHROPIC_BASE_URL=https://kovapi.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
curl https://kovapi.com/anthropic/v1/messages -H "x-api-key: YOUR_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" -d '{"model":"claude-opus-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
```
`"stream": true` se admite como SSE estándar de Anthropic (message_start / content_block_delta / message_delta / message_stop), junto con `/anthropic/v1/messages/count_tokens` y `GET /anthropic/v1/models`.
**Facturación de la caché de prompts**: un acierto de caché (lectura) se factura a **1/10** de la tarifa de entrada (0,1x) y una escritura a **1,25x** (las tarifas por modelo están en la [página de precios](https://kovapi.com/pricing)). Para acertar hacen falta tres cosas: un prefijo idéntico byte a byte, lo bastante largo (Claude Opus >= 4096 tokens, Sonnet >= 2048) y repetido en poco tiempo. Claude Code con un `CLAUDE.md` o system prompt grande sobre un repositorio real acierta en cada turno y paga alrededor de una décima parte por la entrada; las conversaciones cortas del Playground son demasiado breves para cachearse, y eso es lo esperado.

## Consultar tu saldo
Cualquier clave API puede leer el saldo y el gasto de la cuenta, sin iniciar sesión en el panel:
```bash
curl https://kovapi.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```
Compatible con OpenAI (el saldo es `total_available`, así que las herramientas habituales de consulta lo detectan automáticamente):
```bash
curl https://kovapi.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## Códigos de error
| HTTP | Cuándo aparece |
| --- | --- |
| 400 | Un parámetro incorrecto o un modelo desconocido (como `model_not_found`); `error.param` indica el campo. |
| 401 | Falta la clave, o es inválida o está desactivada (`missing_api_key`, `invalid_api_key`). |
| 402 | Saldo insuficiente, o la clave llegó a su presupuesto (`insufficient_quota`). |
| 403 | El modelo no está en la lista de modelos permitidos de esta clave, o la petición llega desde fuera de su lista de IP permitidas (`permission_denied`). |
| 404 | La ruta no existe; o el id del trabajo es desconocido, superó sus 3 días de registro o lo envió otra cuenta (`job_not_found`). |
| 429 | Superaste el límite por minuto de esta clave o la cuota diaria de un modelo gratuito, o el modelo está al límite de su capacidad (`rate_limit_exceeded`). Espera los segundos de `Retry-After` si viene, o unos segundos si no, y reintenta. |
| 502 | El proveedor falló o tardó demasiado y los reintentos automáticos no bastaron; `code` indica el motivo, por ejemplo `upstream_timeout` o `upstream_unavailable`. No se cobra; puedes reintentar. |
| 503 | El modelo está en mantenimiento (`model_maintenance`) o hubo un fallo momentáneo de nuestro lado (`service_unavailable`). No se cobra; reintenta más tarde. |

Lista completa de códigos de error: https://docs.kovapi.com/es/guide/errors/md