Documentation
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.
Overview
Base URL
https://platform.getnox.ai/api/v1
Auth
Bearer API key
Format
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
- Sign in to the console with your Nox account.
- Add credit on the Billing page (Nox plan members start with a one-time $5 credit).
- Create a key on the API keys page and store it as
NOX_API_KEYon your server. - Send your first request:
pip install openaiimport 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)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 listed as "Text" 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.
| id | Input | Input / 1M | Output / 1M | Access |
|---|---|---|---|---|
light-1.1 | Text | $0.30 | $1.20 | Open |
thinking-1.1 | Text | $2.20 | $8.80 | Open |
vela-2.5 | Text, image | $0.20 | $1.00 | Open |
orion-2.1 | Text | $7.00 | $22.00 | Open |
orion-flash-2.1 | Text, image | $0.60 | $2.40 | Open |
orion-2.6-cyber | Text, image | $7.00 | $22.00 | On request |
orion-2.6-med | Text, image | $1.00 | $4.00 | On request |
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:
{
"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.
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)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.
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"}},
],
}],
)Billing and usage
Requests draw from your prepaid API balance. 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 with its tokens and cost, and daily totals are on the Usage page.
Playground requests are billed the same way. 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 a request fails on our side (an error, a broken stream, a timeout or an empty answer), you pay nothing and the whole hold goes back to your balance. The error response says "You were not charged." and carries "cost": { "credits": 0, "usd": 0 }; the request appears on the Logs page as failed and not charged.
If you cancel a request, you pay only for what was generated. 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
A request starts only while your balance is above $0. If a request ends up costing more than what was left, the balance can go below $0, down to -$5.00 and never further; anything past -$5.00 is not charged.
Once a finished request leaves your balance below $0, API access is paused: every API and Playground request returns 402 account_suspended (for example "Your balance is -$1.23. Add credit to bring it back above $0 to continue.") and no model is called. The console stays available for keys, usage, logs and billing, and we send one email to your Nox account address. Access resumes as soon as a top-up brings the balance back to $0 or more. Any top-up ($10 minimum) covers the largest possible debt of $5.
curl https://platform.getnox.ai/api/v1/usage \
-H "Authorization: Bearer $NOX_API_KEY"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).
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.
{
"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 our 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.
Last updated