Skip to main content

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.

This catalog is the naturali offering, not a directory of everything that exists

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​

FieldTypeDescription
modelstringThe 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.
vendorstringThe model maker.
input_modalitiesstring[]Accepted input modalities.
output_modalitiesstring[]Modalities the model can produce.
streamingbooleanWhether the model supports streaming responses.
statusavailable | deprecatedLifecycle 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.
pricingobjectWhat 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_atstring (date-time)When the catalog last confirmed this entry against the provider.

Pricing​

FieldTypeDescription
input_usd_per_tokennumberUSD per input (uncached) token.
output_usd_per_tokennumberUSD 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_tokennumber, nullableUSD 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:

naturali list-models --status available --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:

naturali create-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--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:

naturali list-models

Look one model up, price included:

naturali get-model --model nova-lite-v1