API Reference

This page documents the current stable public OpenAI-compatible API surface.

Only endpoints documented here are product-supported commitments. Other /v1 paths may pass through the gateway, but they are not stable public API promises until they appear in this reference.

Base URL

https://api.nexorouter.com/v1

Authentication

Authorization: Bearer YOUR_NEXOROUTER_API_KEY

Use a NexoRouter key, not a key from the original model provider. The gateway applies that key's status, expiry, budget, and model scope before completing the request.

Request lifecycle

1. Your client sends a key, model ID, and compatible payload.
2. NexoRouter validates the body and applies request and token limits.
3. The gateway checks the model's commercial availability.
4. The request is routed to the configured provider.
5. Known failures are normalized into a safer error response.
6. Usage Logs records the model, key, tokens, cost, latency, status, and available request ID.

A 200 status confirms that the request completed; it does not mean every model returns exactly the same optional fields. Tolerate additional fields and check optional values before using them.

Headers

Request:

Response, when applicable:

GET /models

Returns publicly available model IDs.

Request

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

Response

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

The response may include additional OpenAI-compatible fields. Use the id field as the stable model ID for requests.

POST /chat/completions

Creates one chat completion.

Messages

Each item in messages contains at least role and content. Common text roles are:

Multimodal content, tool messages, and special formats are model-dependent and outside the basic text contract.

Request body

The gateway rejects an empty messages array, non-positive max_tokens, and out-of-range sampling parameters before forwarding the request.

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
  }
}

Response fields

Usage fields and finish reasons can vary by model or provider. Use Usage Logs as the operational source for cost and tracing.

Errors

Documented errors use an OpenAI-compatible shape:

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

Do not log the API key value or sensitive request bodies when capturing an error.

Retries and idempotency

• Retry only transient failures such as 429, 502, and 504.
• Use exponential backoff, jitter, and a small attempt limit.
• Do not automatically retry 400, 401, 403, 404, or 413 without fixing the cause.
• Chat Completions does not document a public idempotency key. A retry can create another completion and another charge.
• For business actions, implement idempotency in your application before executing model output.

Media generation

NexoRouter also supports public image generation, asynchronous video generation, and speech synthesis endpoints for the media model IDs returned by GET /v1/models.

See Image, video, and speech APIs for request formats, polling, pricing units, and limits.

CORS

The public API responds to browser CORS preflight requests and allows GET, POST, PUT, PATCH, DELETE, and OPTIONS. It exposes these headers to the browser:

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

Streaming

Streaming is not listed as a verified public API. Use non-streaming chat/completions unless a NexoRouter page explicitly documents streaming behavior for your client and model.

Embeddings

Embeddings are not listed as a verified public API. Use a separate embeddings provider until NexoRouter documents endpoint behavior, public embedding models, pricing, and usage logs.

Endpoint boundaries

Do not assume support for an endpoint family unless a docs page explicitly documents it.

Endpoint families not yet documented as stable public API:

• OpenAI Responses API
• Anthropic Messages API
• Gemini native API
• audio transcription and translation
• music generation

Next

• POST /v1/chat/completions
• GET /v1/models
• Compatible client SDKs
• Error Handling
• Rate Limits