# Referencia de la API

Todos los endpoints usan la misma clave de API y el mismo saldo. El chat habla los formatos de OpenAI y de Anthropic; las imágenes y los vídeos se generan como trabajos asíncronos.

> https://nezhagate.com/es/docs/api

## URL base

Elige la que corresponda a tu SDK. Las dos comparten clave y saldo.

| Protocolo | URL base | Sirve para |
| --- | --- | --- |
| **Compatible con OpenAI** | `https://nezhagate.com/v1` | Chat, Responses, imágenes, vídeo, lista de modelos, saldo |
| **Anthropic nativo** | `https://nezhagate.com/anthropic` | La API Messages de los modelos Claude (Claude Code, el SDK de Anthropic) |

### Autenticación

Envía tu clave de API en una cabecera en cada petición. Las claves se crean en la página API Keys de la consola y solo se muestran una vez, al crearlas.

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

Los endpoints de Anthropic usan la cabecera `x-api-key` y también aceptan `Authorization: Bearer`.

## Endpoints

Todas las rutas cuelgan de `https://nezhagate.com`. Los endpoints síncronos devuelven el resultado; los de imagen y vídeo devuelven un id de trabajo.

| Método | Ruta | Qué hace |
| --- | --- | --- |
| POST | `/v1/chat/completions` | Chat con cualquier modelo de chat. Con `stream: true` responde en streaming. |
| POST | `/v1/responses` | Chat con el formato Responses de OpenAI (algunos modelos). |
| POST | `/anthropic/v1/messages` | La API Messages nativa de Claude, con streaming, uso de herramientas y caché de prompts. |
| POST | `/anthropic/v1/messages/count_tokens` | Cuenta los tokens de una petición Messages. |
| GET | `/anthropic/v1/models` | Lista de modelos Claude (formato de Anthropic). |
| POST | `/v1/images/generations` | Texto a imagen. Devuelve al momento un id de trabajo (HTTP 202). |
| POST | `/v1/images/edits` | Imagen a imagen. Pasar `image` a la llamada anterior hace lo mismo. |
| GET | `/v1/images/jobs/{id}` | Consulta un trabajo de imagen: estado y resultado. |
| POST | `/v1/videos/generations` | Genera un vídeo. Devuelve al momento un id de trabajo (HTTP 202). |
| GET | `/v1/videos/jobs/{id}` | Consulta un trabajo de vídeo: estado y resultado. |
| GET | `/v1/models` | Lista de los modelos a la venta (formato de OpenAI). |
| GET | `/v1/usage` | Saldo, gasto total y de hoy, y consumo por modelo. |
| GET | `/v1/dashboard/billing/credit_grants` | Consulta de saldo al estilo de OpenAI; el saldo es `total_available`. |

## Trabajos asíncronos (imagen y vídeo)

Las llamadas de imagen y vídeo devuelven al momento HTTP 202 y un id de trabajo; la generación sigue en segundo plano. Consulta el estado con ese id, o recibe el resultado por webhook.

| Estado | Significado |
| --- | --- |
| `queued` | En cola. Incluye `queue_position` (trabajos por delante del tuyo) y `eta_seconds` (espera estimada). |
| `processing` | Generándose. |
| `succeeded` | Terminado. El resultado está en `data[0].url` y el detalle del cobro en `usage`. |
| `failed` | Falló. El motivo está en `error`; los créditos reservados se devuelven íntegros. |

```
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2", "prompt": "a lighthouse at dawn, watercolor", "size": "16:9"}'

# HTTP 202
{"id": "img_3f9a...c2", "object": "image.generation.job", "status": "queued", "model": "nano-banana-2"}
```

```
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H "Authorization: Bearer YOUR_API_KEY"
```

```
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791199400,
  "model": "nano-banana-2",
  "data": [{"url": "https://img.nezhagate.com/i/9f86d081a8....png"}],
  "usage": {"images": 1, "resolution": "1K", "model": "nano-banana-2"}
}
```

- Consulta las imágenes cada 2–3 segundos y los vídeos cada 5–10 segundos. Las consultas son gratis.

- `data[0].url` es un enlace de nuestro alojamiento de medios que se guarda 60 días y luego se borra; descarga lo que quieras conservar.

- Añade `callback_url` al enviar y, cuando termine el trabajo, el mismo resultado que da la consulta llegará a esa URL. [Documentación de webhooks →](https://nezhagate.com/es/docs/webhooks)

## Lista de modelos

Devuelve todos los ID de modelo a la venta, con el formato de OpenAI. Los modelos retirados no aparecen; un modelo que llega pronto sí aparece, pero responde 400 `model_coming_soon` hasta que se abra.

```
curl https://nezhagate.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
```

```
{"object": "list", "data": [{"id": "gpt-5.5", "object": "model", "owned_by": "..."}, {"id": "claude-sonnet-5", "object": "model", "owned_by": "..."}]}
```

## Saldo y consumo

Cualquier clave de API puede leer el saldo y el gasto de la cuenta, sin entrar en la consola.

```
curl https://nezhagate.com/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
```

```
{
  "object": "usage",
  "balance": {"usd": 12.5, "credits": 2500},
  "total": {"cost_usd": 37.5, "requests": 1840, "billed_requests": 1822, "failed_requests": 18},
  "today": {"cost_usd": 1.2, "requests": 64, "billed_requests": 63, "failed_requests": 1},
  "by_model": [
    {"model": "gpt-5.5", "cost_usd": 20.1, "requests": 900, "billed_requests": 896, "failed_requests": 4,
     "prompt_tokens": 1520000, "completion_tokens": 410000, "image_count": 0}
  ]
}
```

`balance.usd` es el saldo en dólares y `balance.credits` el mismo saldo en créditos (1 USD = 200 créditos).

Para herramientas que ya saben consultar un saldo de OpenAI, usa el endpoint al estilo de OpenAI; el saldo es `total_available`.

```
curl https://nezhagate.com/v1/dashboard/billing/credit_grants -H "Authorization: Bearer YOUR_API_KEY"
```

## Formato de error

Todos los errores tienen la misma forma. `code` es un identificador estable y legible por máquina: decide según `code`, nunca según el texto de `message`.

```
{
  "error": {
    "message": "Model not enabled: gpt-9",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}
```

| 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. |
| **404** | El trabajo no existe o pertenece a otra clave (`job_not_found`). |
| **429** | Límite de peticiones, o todas las líneas de este modelo están ocupadas. Espera los segundos que indica la cabecera `Retry-After` y reintenta. |
| **502** | El proveedor falló o tardó demasiado (`upstream_error`). No se cobra; puedes reintentar. |
| **503** | El modelo está en mantenimiento (`model_maintenance`) y no acepta trabajos hasta que vuelva. |

[Lista completa de códigos de error →](https://nezhagate.com/es/docs-guide#errors)

## Límites y reintentos

- Las cuentas no tienen un límite de peticiones por defecto. En la consola puedes dar a cada clave su propio tope de peticiones por minuto, presupuesto diario, límite de gasto total, lista de modelos permitidos y lista de IP permitidas.

- Ante un 429, espera lo que indique la cabecera `Retry-After` y reintenta. Para 502, 503 y tiempos de espera agotados, reintenta con espera exponencial (por ejemplo 1, 2 y luego 4 segundos).

- Las peticiones fallidas nunca se cobran. Si un streaming se corta a medias, solo pagas lo que llegó.

- Si necesitas alta concurrencia de forma sostenida, avísanos con antelación y ampliaremos la capacidad para tu volumen.

## SDK y ejemplos

No hace falta un SDK propio: los SDK oficiales de OpenAI y Anthropic funcionan cambiando `base_url`.

```
from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")
resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="")
```

```
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://nezhagate.com/v1", apiKey: "YOUR_API_KEY" });
const resp = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);
```

```
import anthropic

client = anthropic.Anthropic(base_url="https://nezhagate.com/anthropic", api_key="YOUR_API_KEY")
msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(msg.content[0].text)
```

Más ejemplos listos para ejecutar (Python, Node.js, curl, incluido el flujo asíncrono de imagen y vídeo): [github.com/gaoorange/nezhagate-api-examples](https://github.com/gaoorange/nezhagate-api-examples)

## Documentación de cada modelo

Cada modelo tiene su propia página: valores admitidos de los parámetros, código de ejemplo, formato de respuesta y forma de cobro.

### Modelos de chat

- [GPT-5.6 Sol](https://nezhagate.com/es/docs/gpt-5.6-sol)

- [GPT-5.6 Terra](https://nezhagate.com/es/docs/gpt-5.6-terra)

- [GPT-5.6 Luna](https://nezhagate.com/es/docs/gpt-5.6-luna)

- [GPT-5.5](https://nezhagate.com/es/docs/gpt-5.5)

- [GPT-6 Astra](https://nezhagate.com/es/docs/gpt-6-astra)

- [GPT-6.1 Sol](https://nezhagate.com/es/docs/gpt-6.1-sol)

- [GPT-6 Sol](https://nezhagate.com/es/docs/gpt-6-sol)

- [GPT-6 Luna](https://nezhagate.com/es/docs/gpt-6-luna)

- [Claude Sonnet 4.6](https://nezhagate.com/es/docs/claude-sonnet-4-6)

- [Claude Opus 5](https://nezhagate.com/es/docs/claude-opus-5)

- [Claude Fable 5](https://nezhagate.com/es/docs/claude-fable-5)

- [Claude Sonnet 5](https://nezhagate.com/es/docs/claude-sonnet-5)

- [Claude Opus 5.5](https://nezhagate.com/es/docs/claude-opus-5-5)

- [Claude Sonnet 5.5](https://nezhagate.com/es/docs/claude-sonnet-5-5)

- [Gemini 3.1 Pro](https://nezhagate.com/es/docs/gemini-3.1-pro)

- [Gemini 3.8 Flash](https://nezhagate.com/es/docs/gemini-3.8-flash)

- [Gemini 3.7 Flash](https://nezhagate.com/es/docs/gemini-3.7-flash)

- [Gemini 3.6 Flash](https://nezhagate.com/es/docs/gemini-3.6-flash)

- [Gemini 3.6 Flash High](https://nezhagate.com/es/docs/gemini-3.6-flash-high)

- [Gemini 3.6 Flash Low](https://nezhagate.com/es/docs/gemini-3.6-flash-low)

- [Gemini 3.6 Flash Tiered](https://nezhagate.com/es/docs/gemini-3.6-flash-tiered)

- [Gemini 3 Flash](https://nezhagate.com/es/docs/gemini-3-flash-preview)

- [Gemini 2.5 Flash](https://nezhagate.com/es/docs/gemini-2.5-flash)

- [DeepSeek V4.1 Flash](https://nezhagate.com/es/docs/deepseek-v4.1-flash)

- [DeepSeek V4 Flash 0731](https://nezhagate.com/es/docs/deepseek-v4-flash-0731)

- [GLM-5.3](https://nezhagate.com/es/docs/glm-5.3)

- [GLM-5.3 Flash](https://nezhagate.com/es/docs/glm-5.3-flash)

- [Kimi K3](https://nezhagate.com/es/docs/kimi-k3)

- [Qwen3.7 Max](https://nezhagate.com/es/docs/qwen3.7-max)

- [Qwen3.8 Max](https://nezhagate.com/es/docs/qwen3.8-max)

- [Qwen3.8 Max 0902](https://nezhagate.com/es/docs/qwen3.8-max-0902)

- [Qwen3.8 Flash](https://nezhagate.com/es/docs/qwen3.8-flash)

- [Doubao Seed 2.1 Pro](https://nezhagate.com/es/docs/doubao-seed-2-1-pro)

- [Doubao Seed 2.1 Turbo](https://nezhagate.com/es/docs/doubao-seed-2-1-turbo)

- [Grok 4.7](https://nezhagate.com/es/docs/grok-4.7)

### Modelos de imagen

- [GPT Image 2](https://nezhagate.com/es/docs/gpt-image-2)

- [GPT Image 2.5 Flare](https://nezhagate.com/es/docs/gpt-image-2.5-flare)

- [GPT Image 2.5 Sunburst](https://nezhagate.com/es/docs/gpt-image-2.5-sunburst)

- [Nano Banana 2](https://nezhagate.com/es/docs/nano-banana-2)

- [Nano Banana Pro](https://nezhagate.com/es/docs/nano-banana-pro)

- [Grok Imagine Image](https://nezhagate.com/es/docs/grok-imagine-image)

- [Grok Imagine Image Quality](https://nezhagate.com/es/docs/grok-imagine-image-quality)

### Modelos de vídeo

- [Veo 3.1](https://nezhagate.com/es/docs/veo-3.1)

- [Gemini Omni Flash](https://nezhagate.com/es/docs/gemini-omni-flash)

- [Seedance 2.5](https://nezhagate.com/es/docs/seedance-2.5)

- [Seedance 2.0](https://nezhagate.com/es/docs/seedance-2.0)

- [Seedance 2.0 Fast](https://nezhagate.com/es/docs/seedance-2.0-fast)

- [Seedance 2.0 · Clip](https://nezhagate.com/es/docs/seedance-2.0-clip)

- [Seedance 2.5 · 30s](https://nezhagate.com/es/docs/seedance-2.5-30s)

- [Wan 3.0](https://nezhagate.com/es/docs/wan3.0-video)

- [Wan 3.0 Prime](https://nezhagate.com/es/docs/wan3.0-video-prime)

- [MiniMax H3](https://nezhagate.com/es/docs/minimax-h3)

- [Grok Imagine Video 1.5](https://nezhagate.com/es/docs/grok-imagine-video-1.5)