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: an exact id from GET /v1/models, and one whose is_ready is true. Requesting a model with no live workers returns 429 "No workers available"; 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.

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 with an optional max_tokens cap on reasoning spend. It supersedes the older thinking_budget field, which the schema marks deprecated.
• 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.

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.

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.