Models & output

Do not guess what a model supports. Ask nvoken before starting the turn.

Current providers

The accepted provider names are:

• anthropic
• openai
• xai
• google

grok, gemini, and claude are model families, not provider names. Mistral, Ollama, and OpenRouter are not available through the current nvoken Runtime.

What is in the catalog

Twenty-eight models across those four providers. One per provider is marked recommended — the sensible default when you have no reason to pick something else.

This list moves. Context windows, output ceilings, input media, qualified controls, pricing, and deprecation dates are not repeated here on purpose — they change without a docs deploy, and a table that disagrees with the runtime is worse than no table. GET /v1/models is the live answer, and the next section is how to ask it.

Discover a model

List the curated catalog, then inspect the exact provider and model ID you plan to use:

const catalog = await client.listModels({ provider: "anthropic" });
const model = await client.raw().models.getModel({
  provider: "anthropic",
  modelId: "claude-sonnet-5",
});
 
console.log(catalog.items, model.controls);

The exact model response reports catalog metadata, input media, portable sampling and reasoning controls, tool support, context size when known, and pricing evidence.

Catalog membership is not an account-access check. A model can be advertised while your provider key, region, or plan cannot use it. A real small Turn is the final access test.

Exact lookup also accepts uncataloged IDs. Use the TypeScript SDK for IDs that contain /, reserved characters, or Unicode so the whole ID is encoded as one path segment.

Anywhere a model is accepted, so is the short "anthropic/claude-sonnet-5" string. Reads always echo the canonical object, so a stored response is unambiguous no matter which form the request used.

Models retire on a published date

A catalog entry that is on its way out says so before it goes:

{
  "provider": "anthropic",
  "id": "claude-sonnet-4-5",
  "deprecated": true,
  "deprecated_at": "2026-06-01",
  "retires_at": "2026-10-01",
  "replacement": { "provider": "anthropic", "id": "claude-sonnet-5" }
}

A deprecated model remains available until retires_at. On that UTC date new turns are refused with a 422 model_retired whose details carry the refused model, the retirement date, and the exact replacement to move to. An idempotent replay of a request accepted earlier still succeeds, so a retirement never rewrites work you already have.

Read deprecated_at, retires_at, and replacement from the catalog rather than discovering the date through a failed request.

Sampling and reasoning fail closed

The portable sampling surface currently centers on temperature. Reasoning controls may expose effort or a token budget for qualified models. Tool choice is also model-qualified.

If the exact model descriptor does not advertise a control, omit it. nvoken rejects unsupported or unknown settings before starting the turn rather than quietly changing them.

Omitting a setting preserves the provider default.

Send images and PDFs

Turn input may be a string or an ordered array of text, image, and document blocks:

[
  { "type": "text", "text": "Summarize this chart." },
  {
    "type": "image",
    "source": {
      "media_type": "image/png",
      "data": "<standard-padded-base64>"
    }
  }
]

Images support GIF, JPEG, PNG, and WebP. Documents are PDFs. You may send either type as inline base64 data or as a public HTTPS URL:

{
  "type": "image",
  "source": { "url": "https://cdn.example.com/chart.png" }
}

nvoken downloads a URL once when it creates the turn, stores the bytes, and does not fetch that URL again. The URL may be at most 2,048 characters. You may declare media_type, but it must match the downloaded bytes. Provider file IDs are not accepted as media sources.

Before starting the turn, nvoken checks the decoded format, dimensions, size, request total, and the selected model's declared input capability. Current request bounds allow up to eight media blocks and 16 MiB decoded media in total; an image may be at most 5 MiB and 8000 by 8000 pixels, while one PDF may be at most 16 MiB.

Google models currently accept text plus JPEG, PNG, and WebP images through nvoken. GIF and PDF input are not available for Google models. Check the exact descriptor because capability is model-specific.

Request structured output

outputSchema asks the model to submit one object that nvoken validates against a bounded JSON Schema:

const classifier = client.inline({
  instructions: "Classify the support request.",
  model: "anthropic/claude-sonnet-5",
  outputSchema: {
    type: "object",
    properties: {
      category: { type: "string", enum: ["billing", "technical", "other"] },
      needs_human: { type: "boolean" },
    },
    required: ["category", "needs_human"],
    additionalProperties: false,
  },
});

The schema must be self-contained and use nvoken's documented subset. References and unknown keywords are rejected. The TypeScript SDK preflights the same subset before transport.

The model submits the object through a reserved durable tool, then finishes the turn normally. Prose or a fenced JSON block does not count as a structured submission. If no valid object is accepted, the Turn fails with structured_output_unsatisfied.

Put a cost guardrail on the turn

limits.max_estimated_cost_usd uses nvoken's standard list-price data. It is a guardrail, not a charge reservation or billing ledger.

Inspect the selected model first. Pricing status means:

• priced: nvoken has standard USD pricing for the exact selection.
• unpriced: the catalog knows pricing is absent.
• unknown: the adapter cannot decide before execution.

A cost-capped turn fails closed when usable pricing is unavailable. Omit the cap when intentionally testing a new model whose pricing has not reached the catalog yet.

Provider-side web-search charges are outside this estimate. Bound those with the tool's max_uses setting.

A customer can carry a ceiling across every turn they run, too. See Credits & spending limits.