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

  1. Sign in to the 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
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)

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.

Header
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.

idInputInput / 1MOutput / 1MAccess
light-1.1Text$0.30$1.20Open
thinking-1.1Text$2.20$8.80Open
vela-2.5Text, image$0.20$1.00Open
orion-2.1Text$7.00$22.00Open
orion-flash-2.1Text, image$0.60$2.40Open
orion-2.6-cyberText, image$7.00$22.00On request
orion-2.6-medText, image$1.00$4.00On request
List models
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

FieldTypeDescription
modelstringRequired. A model id from the list above.
messagesarrayRequired. 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_tokensintegerOptional. Upper limit on output tokens. Each model has its own ceiling; larger values are capped.
temperaturenumberOptional. 0 to 2. Lower is more focused.
streambooleanOptional. 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:

Response
{
  "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.

Check your balance status
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 body
{
  "error": {
    "code": "insufficient_balance",
    "type": "invalid_request_error",
    "message": "Your Nox Platform balance is too low for this request…",
    "param": null,
    "request_id": "…"
  }
}
StatusCodeMeaning and what to do
400invalid_requestThe 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.
400tools_not_supportedThe request includes tools, tool_choice, functions, function_call or parallel_tool_calls. Tool calling is not available yet; remove those fields.
400unsupported_parameterA parameter value is not supported, for example n other than 1. Remove it or use the default.
400image_input_not_supportedImages were sent to a model that reads text only. Remove the images or pick a model whose input includes images.
400invalid_imageAn image is not an https URL or a base64 data URL (png, jpeg, gif or webp). Fix the image_url.
400context_length_exceededThe input is too long for the model. Shorten it.
401invalid_api_keyThe key is missing or invalid. Check the Authorization header.
401revoked_api_keyThe key was revoked or has expired. Create a new key in the console.
402insufficient_balanceYour balance cannot cover the hold for this request. Add credit or lower max_tokens.
402account_suspendedYour balance is below $0, so API access is paused. Add credit to bring it back to $0 or more; access resumes straight away.
403insufficient_scopeThe key does not have the permission this endpoint needs. Create a new key in the console.
403model_access_requiredOrion 2.6 Cyber and Orion 2.6 Med need approved access. Request it in the console.
403model_access_pendingYour access request for this model is still being reviewed. Wait for the decision.
404model_not_foundThe model id does not exist. GET /models lists the ids.
404model_not_availableThe model is not offered on the API, for example a retired model. Pick a model from GET /models.
429rate_limit_exceededToo many requests in a minute: 60 per key, 120 per account. Wait for Retry-After, then retry with backoff.
429too_many_failed_requestsMany of your recent requests failed, so new ones are paused for a short while. Wait for Retry-After. Not charged.
429too_many_requests_in_flightToo many of your requests are running at once. Wait for some to finish (Retry-After), then retry. Not charged.
500internal_errorSomething went wrong on the Nox side before the model ran. Retry with backoff. Not charged.
500usage_unavailableGET /usage could not load your balance. Retry.
502model_errorThe model could not complete the request. Retry. Not charged.
502image_read_failedAn attached image could not be read, so the request was not run. Retry. Not charged.
502response_incompleteThe model used its whole output budget before writing an answer. Retry with a larger max_tokens. Not charged.
502generation_failedThe model ended without writing an answer. Retry. Not charged.
503model_overloadedThe model is busy right now. Retry in a few seconds. Not charged.
503model_unavailableThe model is temporarily unavailable. Retry later or use another model. Not charged.
503model_temporarily_unavailableThe model is failing for many callers and is paused for about a minute. Wait for Retry-After or use another model. Not charged.
504timeoutThe 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