Models and readiness

Ambient serves a catalog of open models, published live at GET /v1/models. The field that decides whether a model will actually answer is is_ready, and it changes as workers come and go.

The catalog#

The same data is available live, with no API key:

curl https://api.ambient.xyz/v1/models

Each entry carries the model id, context length, max output length, per-million-token pricing (pricing.input / pricing.output), supported_features (such as tools, json_mode, structured_outputs, reasoning, logprobs), quantization, and the is_ready flag.

Check is_ready before you pin a model#

is_ready tells you whether miners are serving that model right now. Availability tracks live miner capacity, so read it at call time rather than caching it.

• A request to a model that is not ready returns 429 with a message like "No workers available". That is not a rate limit: it means no workers are currently serving that model. Authentication is unaffected. See Errors and retries.
• Check GET /v1/models and pick a model with is_ready: true before pinning one in production, and have a fallback model in mind.
• Miners load-balance, so fanning out many parallel requests to one ready model works.

const res = await fetch("https://api.ambient.xyz/v1/models");
const { data } = await res.json();
 
const ready = data.filter((m: { is_ready: boolean }) => m.is_ready);
console.log(ready.map((m: { id: string }) => m.id));

The ambient/large alias#

ambient/large is an Ambient-managed alias rather than a distinct model: its listed specs and pricing mirror whichever concrete catalog model it currently resolves to, so read them from its own live catalog entry instead of assuming a fixed target. Use it when you want Ambient's default large model without pinning a specific id; pin a concrete id when you need reproducibility.

Pricing comes from the API#

Per-model prices are published in the catalog itself as USD per million tokens (pricing.input and pricing.output), so the table above stays in sync with GET /v1/models.

The API itself does not expose a balance or spend endpoint. Track credits and usage in the Ambient app (Billing and Usage), or meter your own usage locally and price it against the catalog. Token counts are in the usage object of each completion response (for streamed responses, set stream_options: {"include_usage": true} to receive usage in the final chunk).