Skip to main content

Enable naturali models

By the end of this tutorial you will have a project that can generate on any naturali-managed model, with no model-vendor account and no credential of your own.

Three steps:

  1. Create a project — the tenancy boundary everything else lives in.
  2. See what naturali offers — the catalog of managed models and their prices.
  3. Enable them — one provider, and every managed model is available.

Then validate it. Every step is one API call, shown for all three clients. The ids in the responses are examples — copy the ones your own calls return.

Bringing your own key instead?

This tutorial uses naturali's model access, billed at the catalog's price. If you have your own vendor credential and want to use it, do Create a provider instead — the two paths are independent, and a project can use both.

Prerequisites​

You need an account-scoped nat_sk_… API key (or a session JWT from Auth) exported as NATURALI_TOKEN. That is all — there is no vendor key in this tutorial.

A key is project-scoped by default, and a project-scoped key cannot create a project: step 1 answers 403 FORBIDDEN. With one, skip step 1 and export the PROJECT it is scoped to.

export NATURALI_TOKEN=nat_sk_...

Then set your client up:

pnpm add -g @naturali/cli

The CLI reads NATURALI_TOKEN from the environment. See the CLI guide.

1. Create a project​

A project is the isolation boundary: providers, agents and everything else belong to exactly one, and your credential is authorized against it per request.

naturali create-project --name "getting started"
{
"id": "proj_V1StGXR8Z5jdHi6B",
"name": "getting started",
"role": "owner",
"owner_user_id": "user_V1StGXR8Z5jdHi6B",
"status": "active"
}

You are the project's owner — the role that may do anything in it — and its billing owner.

export PROJECT=proj_V1StGXR8Z5jdHi6B

2. See what naturali offers​

The catalog is the same for every project, and it is synced daily against the provider's own listing and published prices. Everything in it is a model naturali serves for you:

naturali list-models --status available
{
"data": [
{
"model": "nova-lite-v1",
"vendor": "amazon",
"input_modalities": ["text", "image", "video"],
"output_modalities": ["text"],
"streaming": true,
"status": "available",
"pricing": {
"input_usd_per_token": 0.000000075,
"output_usd_per_token": 0.0000003,
"cached_input_usd_per_token": 0.00000001875
},
"synced_at": "2026-10-03T07:36:20.628Z"
}
],
"next_cursor": "Z3B0LW9zcy1zYWZlZ3VhcmQtMjBi"
}

The listing is paginated: pass next_cursor back as cursor for the next page until it is null.

Two fields matter later. model is the string you use everywhere a model is named — a provider's default_model, an agent's model. pricing is what generating on it costs in credit, per token.

A model naturali cannot price, or one that does not produce text, is not in this catalog. To generate on one of those, bring your own credential via Create a provider.

3. Enable them​

Create one provider with provider: "naturali". It takes no credential, and it answers the shared naturali provider every project lists.

naturali create-ai-provider --project-id "$PROJECT" \
--name naturali \
--provider naturali \
--default-model nova-lite-v1
{
"id": "aip_N4tur4l1Sh4r3d0",
"name": "naturali",
"provider": "naturali",
"default_model": "nova-lite-v1",
"model_alias_names": ["gemini-3.1-flash-lite", "nova-lite-v1"]
}

There is no credential on it — that is the whole point. default_model is any catalog model the listing showed as available; a value it does not show is refused with 400.

export PROVIDER=aip_N4tur4l1Sh4r3d0

This is the same provider in every project, and calling again answers it again. Models that join the catalog later are served by it too. An agent names the model it runs in its own model.

4. Validate it​

Read the provider back. model_alias_names lists every public name it serves: each model the catalog listing showed should appear, which is the proof that all of them are ready to generate.

naturali get-ai-provider \
--project-id "$PROJECT" \
--ai-provider-id "$PROVIDER"
{
"id": "aip_N4tur4l1Sh4r3d0",
"name": "naturali",
"provider": "naturali",
"default_model": "nova-lite-v1",
"model_alias_names": ["gemini-3.1-flash-lite", "nova-lite-v1"]
}

Each generation on it is metered at the catalog's pricing for the model the agent names.

What's next​

  • Your first agent generation — create an agent on this provider and run it. Set the agent's model to any catalog model to use that model instead of the default.
  • Models — how the catalog stays current, what it covers, and how deprecation is handled.
  • Projects → Project usage — the usage meter, where the cost of every generation shows up.