DOCUMENTATION
Inference API
Call the models the System One Engine serves from your own code: API keys, the request and the answer, plans and limits, and errors.
View as Markdown · for AI agents: llms.txt · skill.md
Call a System One model from your own code: send a state and a few typed questions, and get a calibrated probability for every option back in one request. The models are the ones with a live playground here, served by the System One Engine.
- Base URL:
https://api.systemonemodels.ai - Requests, answers and errors follow the HTTP binding of NoulXP
(
POST /v1/systemone), so a client written for a NoulXP server works here too.
Get an API key
Create one at Settings → API. A key starts with s1_pat_
and is shown once. It calls models and nothing else: it cannot publish, and it
cannot see your private models, so a key that leaks from an app exposes nothing
but your allowance of decisions. Keep it on your server, never in a web page.
Tokens from systemone login can call models too.
Call a model from Python
pip install -U systemonemodels # 0.4 or later
export SYSTEMONE_API_KEY=s1_pat_…
from systemone import Client
client = Client() # reads SYSTEMONE_API_KEY; or Client("s1_pat_…")
result = client.decide(
"nokia/anyjev",
"Customer: I was charged twice and want my money back.",
{
"intent": {
"type": "choice",
"instructions": "What does the customer want?",
"criteria": ["refund", "track delivery", "cancel order"],
},
"angry": {"type": "noul", "instructions": "The customer is angry."},
},
)
print(result["answers"]["intent"]["choice"]) # refund
print(result["answers"]["angry"]["noul"]) # the probability that it is true
client.served_models() lists the models you can call, and client.usage()
what is left of your plan.
Over HTTP
curl https://api.systemonemodels.ai/v1/systemone \
-H "Authorization: Bearer $SYSTEMONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "nokia/anyjev",
"state": "Customer: where is my parcel?",
"questions": {"intent": {"type": "choice",
"instructions": "What does the customer want?",
"criteria": ["refund", "track delivery", "cancel order"]}}}'
| Field | Meaning |
|---|---|
model | The model, as namespace/name |
state | The situation to decide about: text (it may be empty), any JSON value, or a conversation as [{"role", "content"}]; up to 8,000 characters |
questions | 1 to 8 questions, each under an id you choose (letters, digits, ., _, :, -) |
checkpoint | Optional: one of the model's checkpoints; the first one answering when left out |
Each question has a type and instructions:
choicepicks one of 2 to 20 options.criteriais a list of names, or{"name": "description, or null"}.scoreplaces the state on an ordered scale.criteriais a list of 2 to 10 levels, lowest first.noulasks whether the statement ininstructionsis true.criteriais left out, or{"false": "…", "true": "…"}.
The answer
{
"model": "nokia/anyjev",
"version": "0.2.0-qwen3-1.7b",
"checkpoint": "f16",
"answers": {
"intent": { "type": "choice", "choice": "refund",
"probabilities": { "refund": 0.93, "track delivery": 0.02, "cancel order": 0.05 } },
"angry": { "type": "noul", "noul": 0.71 }
},
"usage": { "input_tokens": 212, "output_tokens": 0, "decisions": 2, "billed_tokens": 256 },
"latency_ms": 840.5
}
A score answer carries score, the expected level, with its legend and a
probability per level. System One models answer without generating text, so
output_tokens is always 0. billed_tokens is what a GPU answer was billed
as: its input tokens, or the least a request is billed as when it read fewer (the
minimum today: 256 tokens); 0 for an answer from our CPU servers, which
is free.
Which models
GET /v1/systemone/models lists the models you can call, with their state,
checkpoints and limits. It needs no key. A model can be called once it has a
live playground, which its owner asks for from the model's Playground tab
(how).
state | Meaning |
|---|---|
ready | Loaded: it answers at once |
available | Callable, not loaded now: the engine loads it on the first call, which takes longer (cold_start_seconds is how long its last load took), and the calls after it answer at once |
starting | Its server is bringing it up; try again in a minute |
offline | Its server is not answering |
unavailable | It cannot load on our servers now (too big beside the models they keep loaded, its load failed, or the server cannot load models for a while) |
ready_checkpoints are the checkpoints loaded now, available_checkpoints the
ones you may call (loaded or not), and loaded whether any is loaded. A call
to a model that is not loaded can answer 503 loading (its load carries on: call
again after Retry-After and it answers at once) or 503 no_room (the
server is answering other models; try again after Retry-After).
Plans and limits
A decision is one question answered, so a request with three questions uses three. A request the model could not answer costs nothing. Days and months are UTC.
| Plan | Price | GPU answers | Decisions on CPU | Requests |
|---|---|---|---|---|
| Free | Free | From credit | 500 a day | 1,000,000 a minute |
| Developer | $10 a month | 300M tokens a month, then credit | 100,000 a month | 600 a minute |
| Team | $49 a month | 2B tokens a month, then credit | 1,000,000 a month | 1,200 a minute |
| Dedicated GPU, 24 GB | $299 a month | A 24 GB GPU reserved for an organization, set up by our team | By agreement | 3,000 a minute |
| Dedicated GPU, 48 GB | $599 a month | A 48 GB GPU reserved for an organization, set up by our team | By agreement | 3,000 a minute |
| Enterprise | By agreement | By agreement | By agreement | 3,000 a minute |
On a plan with a decision limit, every answer says what is left, in
X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. GET /v1/usage, with your key or signed in, gives your plan
and your calls by day, model and key; Settings → API shows the
same. The plans, side by side, are on the pricing page; they are
granted by our team until they can be bought online: write to
[email protected].
GPUs and credit
A priced model can answer on a GPU, at its price per million input tokens
(prices). A request is billed as its input tokens, or
as the least a request is billed as when it read fewer (the minimum today:
256 tokens; per request, not per question), which the answer's
usage.billed_tokens says; output tokens are free, and a request that fails
costs nothing. A plan with GPU tokens included pays for them first: Developer,
300M a month; Team, 2B a month for an organization,
which its owners, admins and developers use on every model they call and every
member on its private models. The rest is paid from prepaid credit (an
organization's private models from its payer's): the billed tokens times the
price, rounded up to the next millionth of a dollar. Priced models answer on
GPUs, and those requests do not count against your plan's decisions, while your
plan's tokens left and your credit cover the request. Before a GPU is asked, the
most the request could cost is set aside (generously: several times what it is
billed, a fraction of a cent for a typical request at today's prices; more for a
model that brings its own NoulXP template), and given back once the answer is
charged what it read, never more than was set aside. A request they cannot cover
is not sent, and nothing else takes credit set aside for one, so no answer takes
your balance below zero: only a refund or a chargeback can. Dedicated GPU (an organization's GPU, set up by
our team) and Enterprise plans are billed by agreement. Every account can claim
$5 of free credit once, on Settings → Billing after its
email is verified; it lasts 90 days. Packs of paid credit, which never expire,
are there too, with the statement. Without enough credit you are on the free
plan: models on our CPU servers answer free within its decisions, and a model
only GPUs answer is 402 credits_required, its message saying about how much
the request needs. GET /v1/billing, with your key or signed in, gives your
balance and this month's spend.
The models run on shared CPU servers today: answers take from tens of milliseconds (Laya, Julia 1) to several seconds (language models asked once per option order, like AnyJev).
Errors
The body has the registry's usual detail and code, and NoulXP's
error with a type:
{ "detail": "You have used today's 500 decisions on the Free plan. …",
"code": "quota_exceeded", "errors": [],
"error": { "type": "request_refused", "message": "You have used today's 500 decisions on the Free plan. …" } }
| Status | code | What to do |
|---|---|---|
| 400 | validation_error | Fix the request; errors names the field |
| 401 | unauthorized | Send a valid key as Authorization: Bearer … |
| 403 | insufficient_scope | Use an API key: this token cannot call models |
| 402 | credits_required | The model answers only on GPUs, and your credit cannot cover this request: add credit at Settings → Billing |
| 404 | model_not_found, model_not_served | Check the name, or pick one from GET /v1/systemone/models |
| 422 | bad_question | The model cannot take this question; the message says why |
| 429 | rate_limited, quota_exceeded | Wait Retry-After seconds, or until your plan renews |
| 503 | starting, loading, no_room, busy, timeout, api_paused | Try again after Retry-After seconds |
| 503 | too_big, load_failed | The model cannot run on our servers now; try another, or later |
| 503 | credit_check_unavailable | Your credit could not be checked, so nothing was run on GPUs; try again after Retry-After seconds |