Chat Completions

POST /v1/chat/completions is the core inference endpoint: OpenAI-format in, OpenAI-format out. The field-level reference is below; the quickstart covers your first call, and the OpenAI SDK guide covers client setup.

Request essentials#

Only messages is required by the schema, but in practice you always set:

• model: any exact id listed by GET /v1/models. Every listed model is served; is_ready is a routing flag, not a liveness signal, so do not gate on it. When a model is temporarily out of capacity the API returns 429 with a message such as "No workers available" or "Upstream request failed" (the type varies, so key on the message): retry with short jittered backoff or fail over to another listed model. See Errors and retries.
• max_tokens: give it real headroom. The examples here use 512. The cap covers reasoning and answer combined, and most Ambient models are reasoning models: with a small budget the model can spend every token thinking and return "content": null. Always check finish_reason: "length" with null content means the budget went to reasoning. For short answers, turn thinking off instead of shrinking the budget; see Short answers: turn thinking off.

curl https://api.ambient.xyz/v1/chat/completions \
  -H "Authorization: Bearer $AMBIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ambient/large",
    "messages": [{"role": "user", "content": "Say hello from Ambient."}],
    "max_tokens": 512
  }'

Sampling parameters (temperature, top_p, top_k, min_p, penalties, seed, stop, logprobs) follow OpenAI semantics; each model advertises what it supports in supported_sampling_parameters on GET /v1/models. Tool calling (tools, tool_choice), JSON mode (response_format), and guided generation (guided_json) work on models whose supported_features list them.

Ambient extension fields#

Alongside the standard parameters, the request schema accepts Ambient-specific fields. The three verification flags all default to false:

You can set these flags today, in both streaming and non-streaming requests; they are forward-compatible with the verification fields when those ship. Verified inference covers what the flags are for, the verified and merkle_root response fields, and their current status.

Server-side tools and reasoning control#

Beyond the verification flags, the request schema declares further Ambient-specific fields:

• enabled_tools turns on built-in, server-side tools that the network runs on your behalf, distinct from tools, which declares your own client-side function tools. The schema lists websearch, retrieval, crypto_price, stock_price, weather, currency_convert, and calculator; pass ["*"] to enable all of them.
• reasoning is a reasoning-control object: enabled: false turns thinking off (see Short answers), and an optional max_tokens caps reasoning spend. It supersedes the older thinking_budget field, which the schema marks deprecated. enabled and the top-level reasoning_effort are accepted by the live API ahead of the schema snapshot listing them.
• emit_usage requests a usage object in the response when set; the streaming equivalent is stream_options: {"include_usage": true}.

As with the verification flags, confirm behavior against the specific model you target: capabilities are gated per model by supported_features and supported_sampling_parameters in GET /v1/models.

Short answers: turn thinking off#

GLM 5.2 (ambient/large) reasons before it answers, and max_tokens covers both. For a one-word or one-line reply, a small budget such as 60 comes back 200 with "content": null, finish_reason: "length", the thinking in message.reasoning, and usage.completion_tokens_details.reasoning_tokens greater than zero. Rather than trimming max_tokens, disable thinking with any one of these:

• Model id suffix -nonthinking, for example "ambient/large-nonthinking".
• "reasoning": {"enabled": false} in the request body.
• "reasoning_effort": "none".

Each returns the plain answer in a handful of completion tokens.

curl https://api.ambient.xyz/v1/chat/completions \
  -H "Authorization: Bearer $AMBIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ambient/large",
    "messages": [{"role": "user", "content": "Reply with one word: is 7 prime?"}],
    "reasoning": {"enabled": false},
    "max_tokens": 512
  }'

reasoning_effort values of "low", "medium", and "high" do not reduce GLM 5.2's thinking: it treats all three as "high". Only "none" turns it off. chat_template_kwargs.enable_thinking has no effect either. Whichever route you take, still check finish_reason on every response.

Response#

The spec declares the ChatCompletionResponse shape as choices[].message with the completion, a usage object with prompt, completion, and reasoning token counts, plus the verification fields verified and merkle_root.

Every response also carries an inference-id response header (mirrored as x-request-id), a stable identifier for the request. Log it: it is the durable handle for the inference.

Reasoning models return their thinking in message.reasoning (or, on some models, reasoning_content), separate from message.content. If content comes back null with finish_reason: "length", the token budget was spent on reasoning; raise max_tokens, or for short answers turn thinking off.

Streaming#

Set "stream": true for server-sent events, and "stream_options": {"include_usage": true} to get token counts in the final chunk. Chunks are standard OpenAI chat.completion.chunk objects, with reasoning deltas split across two possible keys depending on the model. Streaming covers the mechanics, the dual delta keys, and stall/truncation detection.

Errors#

Errors and retries covers the full taxonomy, including the two different meanings of 429 and why you should never blindly retry a timed-out completion POST.