# Nox API documentation

> How to call the Nox API: base URL, API keys, Chat Completions requests, streaming, images, billing, rate limits and errors, with curl, Python and Node examples.

The Nox API uses the Chat Completions format. If you already use a Chat Completions client library, set its base URL to Nox, use a Nox API key and pick a Nox model.

Page: https://platform.getnox.ai/docs  
Last updated: November 17, 2026

## Overview

| Base URL | Auth | Format |
| --- | --- | --- |
| https://platform.getnox.ai/api/v1 | Bearer API key | JSON, SSE streaming |

Endpoints: `POST /chat/completions` to generate a reply, `GET /models` to list models and prices, and `GET /usage` to check whether your balance can fund a request. The older `POST /responses` endpoint keeps working for existing integrations.

## Quickstart

1. Sign in to the console (https://platform.getnox.ai/console) with your Nox account.
2. Add credit on the Billing page (Nox plan members start with a one-time $5 credit).
3. Create a key on the API keys page and store it as `NOX_API_KEY` on your server.
4. Send your first request.

Install the client library: `pip install openai` (Python) or `npm install openai` (Node.js).

```bash
curl https://platform.getnox.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $NOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vela-2.5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Write a short poem about the night sky."}
    ]
  }'
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOX_API_KEY"],
    base_url="https://platform.getnox.ai/api/v1",
)

response = client.chat.completions.create(
    model="vela-2.5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Write a short poem about the night sky."},
    ],
)

print(response.choices[0].message.content)
print(response.usage)
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NOX_API_KEY,
  baseURL: "https://platform.getnox.ai/api/v1",
});

const response = await client.chat.completions.create({
  model: "vela-2.5",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Write a short poem about the night sky." },
  ],
});

console.log(response.choices[0].message.content);
console.log(response.usage);
```

## Authentication

Send your key in the `Authorization` header on every request. Keys start with `nox_sk_`. The full key is shown once when you create it and is stored hashed, so it cannot be shown again; create a new key if you lose it.

```
Authorization: Bearer nox_sk_…
```

Keep keys on your server. Never put them in browser code, mobile apps or public repositories. Revoke a key from the console at any time.

## Models

Use the model `id` in the `model` field. Models that read text only reject images with a `400` error. Orion 2.6 Cyber and Orion 2.6 Med need approved access, which you can request on the Model access page of the console.

| Model | id | Input types | Input / 1M tokens | Output / 1M tokens | Max output tokens | Access |
| --- | --- | --- | --- | --- | --- | --- |
| [Light 1.1](https://platform.getnox.ai/models/light-1.1.md) | `light-1.1` | Text only (does not read images) | $0.30 | $1.20 | 16,384 | Open |
| [Thinking 1.1](https://platform.getnox.ai/models/thinking-1.1.md) | `thinking-1.1` | Text only (does not read images) | $2.20 | $8.80 | 32,768 | Open |
| [Vela 2.5](https://platform.getnox.ai/models/vela-2.5.md) | `vela-2.5` | Text, image | $0.20 | $1.00 | 32,768 | Open |
| [Orion 2.1](https://platform.getnox.ai/models/orion-2.1.md) | `orion-2.1` | Text only (does not read images) | $7.00 | $22.00 | 32,768 | Open |
| [Orion Flash 2.1](https://platform.getnox.ai/models/orion-flash-2.1.md) | `orion-flash-2.1` | Text, image | $0.60 | $2.40 | 32,768 | Open |
| [Orion 2.6 Cyber](https://platform.getnox.ai/models/orion-2.6-cyber.md) | `orion-2.6-cyber` | Text, image | $7.00 | $22.00 | 32,768 | Request access |
| [Orion 2.6 Med](https://platform.getnox.ai/models/orion-2.6-med.md) | `orion-2.6-med` | Text, image | $1.00 | $4.00 | 32,768 | Request access |

```bash
curl https://platform.getnox.ai/api/v1/models \
  -H "Authorization: Bearer $NOX_API_KEY"
```

## Chat completions

`POST https://platform.getnox.ai/api/v1/chat/completions`

| Field | Type | Description |
| --- | --- | --- |
| `model` | string | Required. A model id from the list above. |
| `messages` | array | Required. Objects with role (system, user or assistant) and content. User content may be a string or an array of text and image_url parts. |
| `max_tokens` | integer | Optional. Upper limit on output tokens. Each model has its own ceiling; larger values are capped. |
| `temperature` | number | Optional. 0 to 2. Lower is more focused. |
| `stream` | boolean | Optional. true streams the reply as server-sent events. |

Tool calling is not available yet; requests that include `tools` return `400`. The response follows the usual shape:

```json
{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "vela-2.5",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 24, "completion_tokens": 78, "total_tokens": 102 },
  "cost": { "credits": 1, "usd": 0.0002 }
}
```

## Streaming

Set `stream: true` to receive chunks as they are generated. The stream ends with `data: [DONE]`; the last chunk before it carries `usage` and `cost`.

```bash
curl https://platform.getnox.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $NOX_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "vela-2.5",
    "stream": true,
    "messages": [{"role": "user", "content": "Explain DNS in two sentences."}]
  }'

# data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"delta":{"content":"DNS"}}]}
# …
# data: [DONE]
```

```python
stream = client.chat.completions.create(
    model="vela-2.5",
    stream=True,
    messages=[{"role": "user", "content": "Explain DNS in two sentences."}],
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

```javascript
const stream = await client.chat.completions.create({
  model: "vela-2.5",
  stream: true,
  messages: [{ role: "user", content: "Explain DNS in two sentences." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

## Images

Models with image input (Vela 2.5, Orion Flash 2.1, Orion 2.6 Cyber, Orion 2.6 Med) accept `image_url` parts with an https URL or a base64 data URL. Image tokens are billed as input tokens. Light 1.1, Thinking 1.1, Orion 2.1 read text only.

```bash
curl https://platform.getnox.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $NOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vela-2.5",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What does this screenshot show?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/screenshot.png"}}
      ]
    }]
  }'
```

```python
response = client.chat.completions.create(
    model="vela-2.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What does this screenshot show?"},
            {"type": "image_url", "image_url": {"url": "https://example.com/screenshot.png"}},
        ],
    }],
)
```

```javascript
const response = await client.chat.completions.create({
  model: "vela-2.5",
  messages: [{
    role: "user",
    content: [
      { type: "text", text: "What does this screenshot show?" },
      { type: "image_url", image_url: { url: "https://example.com/screenshot.png" } },
    ],
  }],
});
```

## Billing and usage

Before a request runs, its maximum cost is held; when it finishes you are charged for the tokens actually used and the rest of the hold is released.

Every request appears on the Logs page of the console with its tokens and cost, and daily totals are on the Usage page. Playground requests are billed the same way. API credit is a separate balance. Your Nox app plan does not fund API requests, and API calls never use your app allowance.

### Failed requests

Failed requests are not charged. If you cancel a request, you pay only for what was generated. If a request fails on the Nox side (a server error, a timeout or an empty answer), the whole hold is released and you are charged nothing; the error message says you were not charged. The error response carries `"cost": { "credits": 0, "usd": 0 }`, and the request appears on the Logs page as failed and not charged. Cancelling (closing the connection or aborting a stream) charges the input and the output produced up to that point, never more than the hold. Output includes a model's reasoning; for Thinking 1.1, whose reasoning is not streamed, a request cancelled after its answer has started is charged at least half of max_tokens as output.

To protect the service, an account whose requests keep failing is paused for a short while: after 20 failed requests, or $1 of failed work, within an hour, new requests return `429 too_many_failed_requests` with a `Retry-After` header. Requests still running count toward that limit, so an account with many large requests running at once can get `429 too_many_requests_in_flight` until some finish. If a model is failing for many accounts at once, it returns `503 model_temporarily_unavailable` for about a minute instead of taking new requests. Neither is charged.

### Negative balance and paused access

Your balance can go down to -$5.00 to finish requests in progress. A new request is accepted while your balance is above $0 and its maximum cost fits within your balance plus that $5.00 overdraft. Anything past -$5.00 is not charged.

Once your balance is below $0, API and Playground requests are paused until you add credit; the console stays available and we send you one email. Adding credit that brings the balance back to $0 or more resumes access straight away. While access is paused, API and Playground requests return `402 account_suspended` and no model is called. Any top-up ($10 minimum) covers the largest possible debt of $5.

`GET /usage` returns `usage_status`: `available` when requests can run, `depleted` when no credit is left, or `suspended` while access is paused, together with the balance (negative while below $0).

```bash
curl https://platform.getnox.ai/api/v1/usage \
  -H "Authorization: Bearer $NOX_API_KEY"
```

## Rate limits

Each key can send 60 requests per minute, and each account can send 120 per minute across all its keys and the Playground. Over the limit, requests return `429 rate_limit_exceeded` with a `Retry-After` header; wait that long and retry with backoff.

## Errors

Errors return a JSON body with a code, a type, a message, the parameter at fault (or null) and a request id. Keep the request id in your logs; never log the API key.

```json
{
  "error": {
    "code": "insufficient_balance",
    "type": "invalid_request_error",
    "message": "Your Nox Platform balance is too low for this request…",
    "param": null,
    "request_id": "…"
  }
}
```

| Status | Code | Meaning and what to do |
| --- | --- | --- |
| `400` | `invalid_request` | The body is invalid: a missing or malformed field, a value out of range, or more than 8 images. The message and param name the field. Fix the request. |
| `400` | `tools_not_supported` | The request includes tools, tool_choice, functions, function_call or parallel_tool_calls. Tool calling is not available yet; remove those fields. |
| `400` | `unsupported_parameter` | A parameter value is not supported, for example n other than 1. Remove it or use the default. |
| `400` | `image_input_not_supported` | Images were sent to a model that reads text only. Remove the images or pick a model whose input includes images. |
| `400` | `invalid_image` | An image is not an https URL or a base64 data URL (png, jpeg, gif or webp). Fix the image_url. |
| `400` | `context_length_exceeded` | The input is too long for the model. Shorten it. |
| `401` | `invalid_api_key` | The key is missing or invalid. Check the Authorization header. |
| `401` | `revoked_api_key` | The key was revoked or has expired. Create a new key in the console. |
| `402` | `insufficient_balance` | Your balance cannot cover the hold for this request. Add credit or lower max_tokens. |
| `402` | `account_suspended` | Your balance is below $0, so API access is paused. Add credit to bring it back to $0 or more; access resumes straight away. |
| `403` | `insufficient_scope` | The key does not have the permission this endpoint needs. Create a new key in the console. |
| `403` | `model_access_required` | Orion 2.6 Cyber and Orion 2.6 Med need approved access. Request it in the console. |
| `403` | `model_access_pending` | Your access request for this model is still being reviewed. Wait for the decision. |
| `404` | `model_not_found` | The model id does not exist. GET /models lists the ids. |
| `404` | `model_not_available` | The model is not offered on the API, for example a retired model. Pick a model from GET /models. |
| `429` | `rate_limit_exceeded` | Too many requests in a minute: 60 per key, 120 per account. Wait for Retry-After, then retry with backoff. |
| `429` | `too_many_failed_requests` | Many of your recent requests failed, so new ones are paused for a short while. Wait for Retry-After. Not charged. |
| `429` | `too_many_requests_in_flight` | Too many of your requests are running at once. Wait for some to finish (Retry-After), then retry. Not charged. |
| `500` | `internal_error` | Something went wrong on the Nox side before the model ran. Retry with backoff. Not charged. |
| `500` | `usage_unavailable` | GET /usage could not load your balance. Retry. |
| `502` | `model_error` | The model could not complete the request. Retry. Not charged. |
| `502` | `image_read_failed` | An attached image could not be read, so the request was not run. Retry. Not charged. |
| `502` | `response_incomplete` | The model used its whole output budget before writing an answer. Retry with a larger max_tokens. Not charged. |
| `502` | `generation_failed` | The model ended without writing an answer. Retry. Not charged. |
| `503` | `model_overloaded` | The model is busy right now. Retry in a few seconds. Not charged. |
| `503` | `model_unavailable` | The model is temporarily unavailable. Retry later or use another model. Not charged. |
| `503` | `model_temporarily_unavailable` | The model is failing for many callers and is paused for about a minute. Wait for Retry-After or use another model. Not charged. |
| `504` | `timeout` | The request took too long and was stopped. Retry, or lower max_tokens. Not charged. |

Requests refused before they start (`4xx`) cost nothing. Errors on the Nox side (`5xx`, type `server_error`) are not charged either: on chat and response requests their message ends with "You were not charged." and the body carries `"cost": { "credits": 0, "usd": 0 }`. When a response carries a `Retry-After` header, wait at least that many seconds before trying again. During a stream, an error arrives as a final `data: {"error": {...}}` event before `data: [DONE]`.

## FAQ

### Is the Nox API compatible with Chat Completions client libraries?

Yes. The Nox API uses the Chat Completions format, with streaming. Keep your client library, set its base URL to https://platform.getnox.ai/api/v1, use a Nox API key and pick a Nox model id.

### What is the base URL of the Nox API?

https://platform.getnox.ai/api/v1. Chat requests go to POST /chat/completions, the model list with prices is at GET /models.

### Does the Nox API support streaming?

Yes. Set stream to true to receive server-sent events. The stream ends with data: [DONE], and the last chunk before it carries usage and cost.

### Does the Nox API support tool calling?

Not yet. Requests that include tools return a 400 error.

### Am I charged for failed requests?

No. Failed requests are not charged. If you cancel a request, you pay only for what was generated.

### Can my balance go below zero?

Yes, by at most $5. A request starts only while your balance is above $0, and if it costs more than what was left the balance can go down to -$5.00, never further. Once it is below $0, API and Playground requests return 402 account_suspended until you add credit; any top-up that brings the balance back to $0 or more resumes access straight away.

## More from the Nox Platform

- [Nox API overview](https://platform.getnox.ai/index.md)
- [Models](https://platform.getnox.ai/models.md)
- [Pricing](https://platform.getnox.ai/pricing.md)
- [All pages for answer engines (llms.txt)](https://platform.getnox.ai/llms.txt)

Nox Platform is run by Xhealth, Inc., the company behind Nox (https://www.getnox.ai).
