Manual de API

NexoRouter expone una API compatible con OpenAI. El código que ya usa OpenAI SDK normalmente solo necesita cambiar API key, base URL y model ID.

Valores principales

Base URL: https://api.nexorouter.com/v1
Authorization: Bearer YOUR_NEXOROUTER_API_KEY
Model ID: copiar desde Models

Autenticación

Cada request público necesita header Authorization:

Authorization: Bearer YOUR_NEXOROUTER_API_KEY

Si ves invalid_api_key, revisa:

• el header existe;
• Bearer tiene un espacio después;
• la key es de NexoRouter;
• la key está enabled;
• la key no expiró;
• el valor copiado está completo.

Chat Completions

Endpoint:

POST /v1/chat/completions

Campos requeridos:

• model
• messages

Campos opcionales comunes:

• temperature, número de 0 a 2
• top_p, número de 0 a 1
• max_tokens, entero positivo

Ejemplo:

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "Summarize this product in one sentence." }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}

El gateway rechaza requests mal formados antes de reenviarlos. messages vacío, max_tokens inválido, temperature fuera de rango y top_p fuera de rango devuelven invalid_request.

Models

Endpoint:

GET /v1/models

Úsalo para:

• confirmar que la API key es aceptada;
• listar model IDs disponibles públicamente;
• revisar ortografía de model ID.

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

Usa solo los model IDs devueltos por la API pública de modelos para integraciones nuevas.

Facturación

NexoRouter usa saldo prepago. Los requests exitosos consumen quota según modelo, input tokens y output tokens.

Reglas públicas actuales:

• saldo del workspace se comparte entre API keys de la cuenta.
• 1 USD = 500000 quota.
• Una key puede usar workspace balance o presupuesto estricto.
• Una key puede estar sin restricción, limitada a modelos chat o limitada a model IDs específicos.
• Usage Logs muestra modelo, key, tokens, costo, latencia, estado, request ID y contenido de error.
• Si el saldo o presupuesto de key no alcanza, la API devuelve insufficient_quota.

Rate limits y tamaño de request

El gateway tiene límites RPM y TPM configurables. Valores por defecto:

Estos valores pueden cambiar por configuración de deployment.

Requests grandes pueden fallar de dos formas:

• request_too_large: el request individual supera la capacidad de tokens por request. Reduce el input; reintentar el mismo request no funciona.
• token_rate_limit_exceeded: la key o IP actual, opcionalmente combinada con el modelo, superó la ventana TPM. Espera la ventana de retry o reduce tráfico.

Timeouts

Códigos públicos relacionados con timeout:

Para modelos chat normales, empieza con timeout de cliente de al menos 60 segundos. Para modelos lentos tipo reasoning, usa hasta 180 segundos antes de agregar reintentos.

Formato de error

Los errores usan JSON estilo OpenAI:

{
  "error": {
    "message": "Insufficient prepaid balance.",
    "type": "invalid_request_error",
    "code": "insufficient_quota"
  }
}

Códigos frecuentes: