# Documentación para desarrolladores de la API de NezhaGate

Pasarela de API de IA compatible con OpenAI. Base URL: `https://nezhagate.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 $2.0/1M · salida $12.0/1M |
| gpt-5.6-terra | Chat cotidiano, programación agéntica, razonamiento, salida estructurada | /chat/completions | entrada $1.2/1M · salida $7.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.8/1M · salida $4.8/1M |
| gpt-5.5 | Chat, razonamiento, agentes, salida estructurada | /chat/completions | entrada $0.7/1M · salida $4.2/1M |
| gpt-6-astra | Razonamiento profundo, programación agéntica, contexto muy largo, entrada de imagen, salida estructurada | /chat/completions | entrada $2.8/1M · salida $14.0/1M |
| gpt-image-2 | Texto a imagen, imagen a imagen, portadas, carteles, ilustraciones | /images/generations | 1K $0.015 · 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.015 · 2K $0.025 · 4K $0.04 |
| gpt-image-2.5-sunburst | Texto a imagen, imagen a imagen, portadas, carteles, ilustración, tipografía | /images/generations | 1K $0.015 · 2K $0.025 · 4K $0.04 |
| nano-banana-2 | Texto a imagen, imagen a imagen, portadas, carteles, ilustraciones | /images/generations | 1K $0.025 · 2K $0.0375 · 4K $0.0625 |
| nano-banana-pro | Texto a imagen, imagen a imagen, portadas, carteles, ilustraciones, infografías | /images/generations | 1K $0.04 · 2K $0.06 · 4K $0.1 |
| 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 |
| 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 |
| gemini-3.7-flash | Chat, razonamiento, razonamiento adaptativo, entrada de imagen, contexto muy largo | /chat/completions | entrada $0.6/1M · salida $3.6/1M |
| gemini-3.6-flash | Chat, razonamiento, entrada de imagen, contexto muy largo | /chat/completions | entrada $0.6/1M · salida $3.6/1M |
| gemini-3.6-flash-high | Razonamiento profundo, tareas complejas, entrada de imagen, contexto muy largo | /chat/completions | entrada $0.6/1M · salida $3.6/1M |
| gemini-3.6-flash-low | Chat a alta velocidad, gran volumen, baja latencia, entrada de imagen | /chat/completions | entrada $0.6/1M · salida $3.6/1M |
| gemini-3.6-flash-tiered | Razonamiento adaptativo, chat, razonamiento, entrada de imagen | /chat/completions | entrada $0.6/1M · salida $3.6/1M |
| gemini-3-flash-preview | Chat, razonamiento, alta concurrencia, baja latencia | /chat/completions | entrada $0.3/1M · salida $1.2/1M |
| gemini-2.5-flash | Chat, alta concurrencia, baja latencia, multimodal | /chat/completions | entrada $0.3/1M · salida $1.2/1M |
| veo-3.1 | Texto a vídeo, imagen a vídeo, clips cortos, material comercial | /videos/generations | $0.075 / clip · próximamente, todavía no se puede llamar |
| seedance-2.5 | Cortos de plano largo, entrada con varias referencias, material comercial | /videos/generations | $0.632 / clip |
| seedance-2.0 | Clips cortos, material comercial | /videos/generations | $0.6 / clip |
| seedance-2.0-fast | Material en lote, validación rápida de ideas | /videos/generations | $0.4 / clip |
| seedance-2.0-mini | Borradores en volumen, iteración de bajo coste | /videos/generations | $0.33 / clip |
| wan3.0-video | Narrativa de plano largo, composición con varios materiales, reescritura de vídeo | /videos/generations | $0.18 / clip |
| wan3.0-video-prime | Material con plazo ajustado, pruebas de plano en lote | /videos/generations | $0.24 / clip |
| minimax-h3 | Metraje en alta definición, clips cortos con sonido | /videos/generations | $0.18 / clip |
| 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://nezhagate.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://nezhagate.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 estable de `img.nezhagate.com`). **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://nezhagate.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://nezhagate.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 estable rehospedado). Entre 1 y 2 minutos por clip, facturado por clip y reembolsado íntegramente si falla. La orientación la fija `size`: `16:9` horizontal (por defecto) o `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://nezhagate.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model":"seedance-2.5","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://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```
Modelos de vídeo disponibles: `seedance-2.5`, `seedance-2.0`, `seedance-2.0-fast`, `seedance-2.0-mini`, `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/seedance-2.5](/docs/seedance-2.5).

## 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://nezhagate.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://nezhagate.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
curl https://nezhagate.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](/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://nezhagate.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://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## Códigos de error
| Código | Significado |
| --- | --- |
| 401 | Falta la clave API o no es válida |
| 402 | Saldo insuficiente o clave por encima de su cuota |
| 400 | Modelo o parámetro no soportado |
| 429 | Límite de tasa del proveedor |
| 502 | Fallaron todas las rutas de proveedor |