Referencia de API

Esta página documenta la superficie pública estable actual de la API compatible con OpenAI.

Solo los endpoints documentados aquí son compromisos de soporte del producto. Otros paths bajo /v1 pueden pasar por el gateway, pero no son promesas de API pública estable hasta que aparezcan en esta referencia.

Base URL

https://api.nexorouter.com/v1

Autenticación

Authorization: Bearer YOUR_NEXOROUTER_API_KEY

Usa una key de NexoRouter, no una key del proveedor original. El gateway aplica estado, expiración, presupuesto y alcance de modelos de esa key antes de completar el request.

Flujo de un request

1. Tu cliente envía una key, model ID y payload compatible.
2. NexoRouter valida el body y aplica límites de requests y tokens.
3. El gateway comprueba disponibilidad comercial del modelo.
4. El request se enruta al proveedor configurado.
5. La respuesta se normaliza cuando hay un error conocido.
6. Usage Logs registra modelo, key, tokens, costo, latencia, estado y request ID disponible.

Un status 200 confirma que el request terminó, no que todos los modelos tengan exactamente los mismos campos opcionales. Programa el cliente para tolerar campos adicionales y comprueba valores opcionales antes de usarlos.

Headers

Request:

Response, cuando aplique:

GET /models

Devuelve model IDs disponibles públicamente.

Request

curl https://api.nexorouter.com/v1/models \
  -H "Authorization: Bearer $NEXOROUTER_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "kimi-k2.6",
      "object": "model"
    }
  ]
}

La respuesta puede incluir campos adicionales compatibles con OpenAI. Usa id como model ID estable para requests.

POST /chat/completions

Crea una respuesta de chat.

Mensajes

Cada item de messages contiene como mínimo role y content. Los roles de texto comunes son:

Contenido multimodal, tool messages y formatos especiales dependen del modelo y no forman parte del contrato de texto básico.

Request body

El gateway rechaza un array messages vacío, max_tokens no positivo y sampling parameters fuera de rango antes de enviar el request al proveedor.

Request

curl https://api.nexorouter.com/v1/chat/completions \
  -H "Authorization: Bearer $NEXOROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "messages": [
      { "role": "user", "content": "Write one short launch checklist." }
    ],
    "max_tokens": 256
  }'

Response

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Create an API key, choose a model, test in Playground, and monitor usage logs."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 18,
    "total_tokens": 38
  }
}

Campos de response

Los campos de uso y finish reason pueden variar por modelo o proveedor. Usa Usage Logs como fuente operativa para costo y trazabilidad.

Errores

Los errores documentados usan una forma compatible con OpenAI:

{
  "error": {
    "message": "Human-readable explanation",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}

No registres el valor de la API key ni bodies sensibles al capturar un error.

Reintentos e idempotencia

• Reintenta solo fallos transitorios como 429, 502 y 504.
• Usa backoff exponencial, jitter y un máximo pequeño de intentos.
• No reintentes automáticamente 400, 401, 403, 404 o 413 sin cambiar la causa.
• Chat Completions no documenta una key de idempotencia pública. Un retry puede generar otra completion y otro cargo.
• Para acciones de negocio, implementa idempotencia en tu aplicación antes de ejecutar el resultado del modelo.

Generación multimedia

NexoRouter también ofrece generación pública de imágenes, video asíncrono y síntesis de voz para los IDs multimedia devueltos por GET /v1/models.

Consulta APIs de imagen, video y voz para ver formatos de request, consulta de tareas, unidades de precio y límites.

CORS

La API pública responde a preflight CORS de navegador y permite GET, POST, PUT, PATCH, DELETE y OPTIONS. Expone estos headers al navegador:

• x-request-id
• x-ratelimit-limit
• x-ratelimit-remaining
• retry-after

Streaming

Streaming no aparece como API pública verificada. Usa chat/completions sin streaming salvo que una página de NexoRouter documente explícitamente el comportamiento de streaming para tu cliente y modelo.

Embeddings

Embeddings no aparece como API pública verificada. Usa un proveedor separado de embeddings hasta que NexoRouter documente comportamiento del endpoint, modelos públicos, precios y Usage Logs.

Límites de endpoints

No asumas soporte para una familia de endpoints salvo que una página la documente explícitamente.

Familias que todavía no están documentadas como API pública estable:

• OpenAI Responses API
• Anthropic Messages API
• Gemini native API
• transcripción y traducción de audio
• generación de música

Siguiente

• POST /v1/chat/completions
• GET /v1/models
• SDKs de cliente compatibles
• Manejo de errores
• Rate Limits