Models
The naturali model catalog — what the platform can serve, and what it costs.
Overview
The catalog lists every model naturali offers, with capability metadata,
lifecycle status and the price. It is synced daily, so it reflects what is
available today rather than a snapshot: new models appear on their own, retired
models flip to deprecated, and pricing stays current. Most models are synced
from the provider's own listing and published prices; a provider without a
reliable listing or price API (Vertex, and Anthropic's own API) is instead
synced from a curated set naturali maintains, so a listed model is one naturali
has verified it can serve. Claude models are served from two sources: those
naturali can run on Bedrock come from there, and the newer ones from
Anthropic's own API.
Where a provider lists a model but publishes no price for it — the Anthropic
models on Bedrock — the listing is still live and only the price is curated, on
the same rule: naturali verifies it can serve the model before offering it — by
generating on it through this API, which is why a model the provider lists is
not always one this catalog carries.
Every project lists
the shared naturali provider,
which serves every model in this catalog. No credentials of yours are
involved; it runs on naturali's own model access and its usage is metered at
the catalog's pricing.
A model's model is the only string this API asks you for — the same value
goes in a provider's default_model and in an Agent's model.
Enable naturali models
reads it, with its pricing, off the listing.
A model naturali cannot price, one that produces something other than text
(embeddings, images, audio), or one that takes no text input (speech-only), is
not listed here — the runtime's usage meter
is token-based, so naturali cannot meter those truthfully and does not offer
them. To generate on one, register your own credentials as an
AI provider and ask that provider what it serves with
GET /v1/projects/{project_id}/ai-providers/{ai_provider_id}/models,
which answers for your credential rather than for naturali's.
Embeddings are the exception: one embedding model of this
API's serves every project, so you neither pick nor register one.
The catalog itself is read-only — there is no create/update/delete, only listing and lookup.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Models.
Data Model
Model
| Field | Type | Description |
|---|---|---|
model | string | The model's name, and the only model string this API accepts or returns. Use it verbatim as a provider's default_model and as an agent's model. It is naturali's own name, not the vendor's: it states a version explicitly and never changes, so a vendor relabelling its model cannot move a name you have already written down. A vendor's own invocation string is refused where this is expected — one model has one name. |
vendor | string | The model maker. |
input_modalities | string[] | Accepted input modalities. |
output_modalities | string[] | Modalities the model can produce. |
streaming | boolean | Whether the model supports streaming responses. |
status | available | deprecated | Lifecycle status, from the provider's own listing at the last sync. A model the provider stops listing — or reports as legacy or deprecated — flips to deprecated and stays in the catalog, so a project already generating on it can see what happened to it. |
pricing | object | What generating on this model costs in credit, in USD per token: the figure the shared provider's price book holds, /usage reports as cost_usd and the balance is debited. Always present: a model naturali cannot price is not in this catalog. Refreshed by the daily sync. |
synced_at | string (date-time) | When the catalog last confirmed this entry against the provider. |
Pricing
| Field | Type | Description |
|---|---|---|
input_usd_per_token | number | USD per input (uncached) token. |
output_usd_per_token | number | USD per output token. Reasoning ("thinking") tokens are output tokens: on a model that reasons by default they are counted in output_tokens and billed at this rate, and can be most of the output on a short answer. A rate alone therefore does not size a request on such a model. |
cached_input_usd_per_token | number, nullable | USD per cache-read input token; null when the model does not price caching (cached tokens are then billed at the input rate). |
Key Concepts
One model, one name
model is naturali's own name for the model, not the vendor's. It states a
version explicitly (nova-lite-v1, deepseek-v3.2, gemini-3.7-flash) and it
never changes — a vendor relabelling its model cannot move a name your
agents already use.
The vendor's own invocation string is deliberately not published. It would be a
second string that also works, and a model with two names is a model whose
identity you have to keep translating: which one goes in the agent, which one
shows up in a trace, which one your teammate pasted. Sending one where a model
is expected is a 400, not a silent success.
The name is the one string on every surface: an agent read, a generation's
output.model, a trace, a usage event, a price row and an agent's builtin
tool result all answer it.
That is also why the catalog does not tell you which cloud serves a model. You chose naturali; which vendor runs it, in which region, through which invocation mode, is naturali's problem — and it can change without your configuration changing.
A retired model stays in the catalog
status is the lifecycle axis and it is independent of the offering. A model
the provider stops listing — or reports as legacy — flips to deprecated and
stays listed, because a project already generating on it needs to see what
happened to it. What changes is that the shared naturali provider no longer
serves it: naming it beside that provider — an agent's model, a route target
or a generation's model — answers 400 MODEL_NOT_OFFERED.
Filter on it to see only what is current:
- CLI
- SDK
- curl
naturali list-models --status available --vendor amazon
const { data } = await naturali.models.listModels({
query: { status: 'available', vendor: 'amazon' },
});
curl -G https://api.naturali.ai/v1/models \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-d status=available -d vendor=amazon
Generating on the shared provider
Every project lists the shared naturali provider,
which serves every model this catalog lists, from every vendor, under one id.
Name its id and a catalog model; another model of another vendor needs only a
different model:
- CLI
- SDK
- curl
naturali create-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--ai-provider-id aip_N4tur4l1Sh4r3d0 \
--model nova-lite-v1 \
--name support-triage
const { data: agent } = await naturali.agents.createAgent({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
ai_provider_id: 'aip_N4tur4l1Sh4r3d0',
model: 'nova-lite-v1',
name: 'support-triage',
},
});
curl -X POST \
"https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ai_provider_id": "aip_N4tur4l1Sh4r3d0",
"model": "nova-lite-v1",
"name": "support-triage"
}'
Its usage events answer the public model and are priced at this catalog's
pricing.
Enabling naturali models
There is nothing to enable. Every project lists the shared naturali provider
first in
GET /v1/projects/{project_id}/ai-providers,
and it serves the whole catalog, models that join it later included. To
generate on any entry, set the agent's model to that entry's catalog model
and its ai_provider_id to the shared provider's id.
Enable naturali models walks through
it.
Pricing follows the provider
pricing is what generating on the model costs in credit, per token: the same
figure the shared provider meters at, /usage reports as cost_usd
and your balance is debited. The daily sync keeps it aligned with the
provider's published price — on the catalog and on the shared provider,
whose metering picks up the new price from the moment it takes
effect. Prices already metered are never rewritten: a usage receipt shows the
price that was in force when the generation ran.
BYOK usage carries no naturali LLM price at all (pricing: null does not
mean free — it means your own provider bills you directly).
Reasoning tokens are output tokens
A model that reasons ("thinks") before answering charges you for the thinking.
Those tokens are counted in output_tokens and billed at
output_usd_per_token — there is no separate reasoning rate, and no way to opt
out of paying for them on a model that reasons by default.
They can dominate a small request. One measured generation on
gemini-3-flash-preview, prompted Reply with exactly one word: hello and
answering Hello, spent 13 input tokens and 119 output tokens — 118 of the
119 were reasoning:
{
"key": "gemini-3-flash-preview",
"cost_usd": 0.0003635,
"input_tokens": 13,
"output_tokens": 119,
"components": [
{ "component": "input_tokens", "quantity": 13, "cost_usd": 0.0000065 },
{ "component": "output_tokens", "quantity": 119, "cost_usd": 0.000357 },
{ "component": "reasoning_tokens", "quantity": 118, "cost_usd": null }
]
}
The reasoning_tokens component reports the quantity for visibility; its
cost_usd is null because output_tokens already prices it, not because it
was free. Reading the catalog rate alone and sizing that reply at one or two
output tokens would have under-estimated it by around 100x.
Two things follow. Sizing a workload from the rates needs an output estimate
that includes thinking — for a short answer on a reasoning model that is tens
to hundreds of tokens, not the length of the answer. And a tokens or
cost_usd quota sized the same way is consumed just as fast: the
cap is enforced correctly, against usage larger than the estimate behind it.
Cap a project's spend
sizes one from measured usage instead.
The catalog does not currently carry a per-model flag for this — whether a model
reasons, and how much, is behaviour rather than a published price dimension.
Measure it for your own prompts with
GET /v1/projects/{project_id}/usage,
which breaks a bucket down into the components above.
A catalog entry is not a region guarantee
The catalog answers what naturali serves, not where your own credential can
reach it. Through a naturali-managed provider the two are the same — naturali
runs these models in a configuration it has verified. Through a provider of your
own they can differ: a model is served in some regions and not others, so a
provider pinned to a regional config.location can get a 404 for a model this
catalog lists.
Vertex is where this bites today. The Gemini 3 models are served in the
global location only, so a provider of your own configured for a specific
region cannot reach them. Set config.location to global for those, or ask
the provider record itself with
GET /v1/projects/{project_id}/ai-providers/{ai_provider_id}/models,
which answers with that record's own credential and configuration.
Deprecation keeps history
A model the provider stops listing — or reports as legacy or deprecated —
flips to status: "deprecated" at the next sync and stays in the catalog, so
a project already generating on it can see what happened to it. The shared
naturali provider stops serving it at that sync.
Examples
List the whole catalog:
- CLI
- SDK
- curl
naturali list-models
const { data } = await naturali.models.listModels();
curl https://api.naturali.ai/v1/models \
-H "Authorization: Bearer $NATURALI_TOKEN"
Look one model up, price included:
- CLI
- SDK
- curl
naturali get-model --model nova-lite-v1
const { data } = await naturali.models.getModel({
path: { model: 'nova-lite-v1' },
});
curl https://api.naturali.ai/v1/models/nova-lite-v1 \
-H "Authorization: Bearer $NATURALI_TOKEN"