Documentación para desarrolladores de la API de NezhaGate

Inicio rápido

Solo tienes que cambiar la Base URL y la clave API, y tu SDK de OpenAI actual funciona sin tocar nada más.

https://nezhagate.com/v1

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": "Escribe una breve presentación de producto para una API de IA"}], "stream": false}'

Los parámetros completos de la petición, los ejemplos y el uso asíncrono de cada modelo están en su propia página de documentación: ábrela desde la tabla de modelos y precios de abajo.

Más ejemplos ejecutables (Python / Node / curl, incluido el flujo asíncrono de imagen y vídeo): github.com/gaoorange/nezhagate-api-examples

Autenticación

Todas las llamadas a la API requieren un Bearer Token.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Modelos y precios

Los parámetros completos de la petición, los ejemplos y el uso asíncrono de cada modelo están en su propia página de documentación: ábrela desde la tabla de modelos y precios de abajo.

Úsalo en una aplicación (sin código)

En cualquier aplicación que hable la API de OpenAI, rellena estos tres campos; no hace falta programar:

Verificado con ChatBox, Cherry Studio, NextChat, LobeChat, Immersive Translate, Open WebUI, etc.

Guías paso a paso para clientes: SillyTavern · Cherry Studio · Cline

API nativa de Anthropic (Claude Code)

Además de la ruta compatible con OpenAI, los modelos Claude exponen la API nativa de mensajes de Anthropic. Apunta Claude Code (o cualquier SDK de Anthropic) a la Base URL de abajo y usa tu clave de la pasarela como x-api-key: el razonamiento, el uso de herramientas y la caché de prompts se conservan de forma nativa.

export ANTHROPIC_BASE_URL=https://nezhagate.com/anthropic
export ANTHROPIC_API_KEY=YOUR_API_KEY
# claude-sonnet-4-6 / claude-opus-5 / claude-fable-5 / claude-opus-5-5 / claude-sonnet-5-5

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-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'

Modelos: claude-opus-5-5, claude-sonnet-5-5, claude-opus-5, claude-sonnet-5, claude-fable-5, claude-sonnet-4-6. Se factura exactamente igual que /v1, por token.

Facturación de la caché de prompts: los aciertos de caché (lectura) se facturan a 1/10 (0,1×) de la tarifa de entrada y las escrituras a 1,25× (las tarifas por modelo están en la página de precios). Para acertar hace falta un prefijo estable y lo bastante largo (Claude Opus ≥ 4096 tokens, Sonnet ≥ 2048) repetido en poco tiempo: Claude Code con un CLAUDE.md o system prompt grande sobre un repositorio real acierta en cada turno y reduce el coste de entrada a ~1/10. Las conversaciones cortas del Playground son demasiado breves para cachearse.

Generación de vídeo (asíncrona)

Texto a vídeo e imagen a vídeo son trabajos asíncronos: la llamada 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 status=succeeded y lee el resultado en data[0].url (un mp4 rehospedado). De 1 a 12 minutos por clip. Hay dos modos de facturación: Veo 3.1 se factura por clip; Seedance 2.x y MiniMax H3 se facturan por segundo (tarifa x duración). Ambos retienen exactamente lo que cobran y reembolsan por completo si falla. Fija la relación de aspecto con size (16:9 horizontal es la predeterminada); para imagen a vídeo pasa una referencia de primer fotograma en image.

curl https://nezhagate.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", "tier": "fast", "resolution": "1080p", "size": "16:9"}'

curl https://nezhagate.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

Modelos de vídeo: veo-3.1 gemini-omni-flash kling-4.0 seedance-2.5-token seedance-2.5-token-draft seedance-2.5 seedance-2.0 seedance-2.0-fast seedance-2.0-clip seedance-2.5-30s wan3.0-video wan3.0-video-prime minimax-h3 grok-imagine-video-1.5

Webhooks: recibe un aviso cuando termine una tarea

La generación de vídeo e imagen es asíncrona: envías la petición, recibes un ID de tarea y el resultado llega un poco después. En lugar de consultar el estado una y otra vez, deja que enviemos el resultado a tu servidor cuando termine la tarea y que te avisemos cuando se esté agotando tu saldo.

¿Prefieres no consultar el estado? Añade callback_url al enviar la tarea y te enviaremos el resultado a tu servidor cuando termine, o configura un endpoint por defecto en la consola. Documentación de webhooks →

Agent Skills: vídeos con una frase desde tu asistente de código

Instala el skill de NezhaGate en Claude Code, Codex, Cursor u otro asistente compatible y pide en lenguaje natural «convierte esta imagen en un vídeo de 8 s con seedance-2.5 y guárdalo en ./out»: el asistente elige el modelo, sube los archivos, espera el render y guarda el resultado. Disponible ahora: el skill de vídeo Seedance 2.5 / 2.0.

npx skills add https://nezhagate.com

export NEZHAGATE_API_KEY=YOUR_API_KEY

github.com/gaoorange/nezhagate-skills · Vídeo de demostración (8 s, una sola petición)

Notas de integración para copiar a una IA

Envía todo el bloque de abajo a Codex / Claude Code / Cursor y sabrá cómo integrarlo. También puedes usar «Copiar página» arriba a la derecha para copiar el documento entero.

Integrate NezhaGate through its OpenAI-compatible API.
Base URL: https://nezhagate.com/v1
API Key: read it from the environment variable NEZHAGATE_API_KEY.
Claude models can also use the native Anthropic protocol (for Claude Code / the Anthropic SDK): ANTHROPIC_BASE_URL=https://nezhagate.com/anthropic, headers x-api-key=API Key and anthropic-version: 2023-06-01, POST /anthropic/v1/messages (max_tokens is required), models claude-sonnet-4-6 / claude-opus-5 / claude-fable-5 / claude-opus-5-5 / claude-sonnet-5-5.
Chat models (/chat/completions): gpt-5.6-sol / gpt-5.6-luna / gpt-6-astra / gpt-6.1-sol / gpt-6-sol / gpt-6-luna / claude-sonnet-4-6 / claude-opus-5 / claude-fable-5 / claude-opus-5-5 / claude-sonnet-5-5 / gemini-4-argon / gemini-3.1-pro / gemini-3.8-flash / deepseek-v4.1-flash / deepseek-v4-flash-0731 / glm-5.3 / qwen3.8-max / qwen3.8-flash / grok-4.7
Image models (text-to-image /images/generations; image-to-image /images/edits or add an image parameter): gpt-image-2 / gpt-image-2.5-flare / gpt-image-2.5-sunburst / nano-banana-2 / nano-banana-pro / nano-banana-2.1 / grok-imagine-image / grok-imagine-image-quality
Video models (/videos/generations, async jobs; add reference images for image-to-video; how each model uses them is in its own doc): veo-3.1 / gemini-omni-flash / kling-4.0 / seedance-2.5-token / seedance-2.5-token-draft / seedance-2.5 / seedance-2.0 / seedance-2.0-fast / seedance-2.0-clip / seedance-2.5-30s / wan3.0-video / wan3.0-video-prime / minimax-h3 / grok-imagine-video-1.5
Auth: Authorization: Bearer YOUR_API_KEY
Requirements (chat): return choices[0].message.content; on 401 check the key, 402 means insufficient balance, 429/5xx can be retried.
Requirements (images, async): POST /images/generations or /images/edits returns HTTP 202 with a job id right away ({"id":"img_...","object":"image.generation.job","status":"queued"}); then poll GET /v1/images/jobs/{id} until status=succeeded and read data[0].url (an img.nezhagate.com link kept for 15 days; download it or copy it to your own storage). Do not read data right after submitting.
Requirements (video, async): POST /videos/generations returns HTTP 202 with a job id (object=video.generation.job); then poll GET /v1/videos/jobs/{id} until status=succeeded and read data[0].url (a re-hosted mp4 link kept for 15 days). Render time varies by model (from a minute or two to over an hour); failed jobs are refunded in full.

Consultar saldo y uso

Usa cualquier clave API para leer el saldo restante y el gasto de la cuenta, sin iniciar sesión en el panel. Lo más sencillo: GET /v1/usage. También compatible con OpenAI: /v1/dashboard/billing/credit_grants (el saldo es total_available).

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

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

Códigos de error

Los errores de los endpoints /v1 tienen la forma de abajo (los endpoints /anthropic usan el formato propio de Anthropic). code es un identificador estable y legible por máquina: decide según code, nunca según el texto de message.

{
  "error": {
    "message": "human readable",
    "type": "invalid_request_error | authentication_error | permission_error | insufficient_quota | rate_limit_error | server_error",
    "code": "stable_snake_case",
    "param": "field_name_or_null"
  }
}

Lista completa de códigos de error →

max_tokens en modelos de razonamiento — Gemini 3.x Flash (3-flash-preview / 3.6 / 3.7 / 3.8, en todos sus niveles) gastan el presupuesto en razonamiento oculto antes de escribir la respuesta visible, así que un presupuesto pequeño se agota antes de que empiece la respuesta: según nuestras mediciones, max_tokens=16 falla directamente y 32 / 64 devuelven un valor erróneo pero plausible con finish_reason=length. La pasarela eleva el presupuesto de salida de esos modelos a un mínimo de 512 (solo se cobran los tokens realmente usados), pero envía tú mismo >=512; trata cualquier finish_reason=length como posiblemente truncado y reintenta con un max_tokens mayor.

Preguntas habituales sobre integración, facturación, modelos y seguridad. Preguntas frecuentes de NezhaGate →