Live now · Get your API key

Quickstart

Create an API key, make your first request against the Ambient network, and understand what comes back, all in under five minutes.

A first completion against https://api.ambient.xyz/v1 takes a key and one request. The API is OpenAI-compatible, so an existing client only needs a new base URL and key.

  1. Get an API key#

    Create a key at app.ambient.xyz/keys. Requests authenticate with a standard bearer header:

    Authorization: Bearer $AMBIENT_API_KEY

    The model catalog endpoint requires no authentication, so you can browse the network before you have a key:

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

  2. Make your first request#

    The examples use ambient/large, an Ambient-managed model alias. Any model id from GET /v1/models works, provided its is_ready flag is true.

    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
  }'

    max_tokens is 512 because it caps reasoning and answer combined. Reasoning models can spend a small budget entirely on thinking and return null content.

    If the request returns 429 with a message like "No workers available", the model has no miners serving it right now. Pick another model whose is_ready is true, and see Errors and retries.

  3. What you got back#

    The body is a standard OpenAI-style chat completion:

    Field What it is
    id Completion id (chatcmpl-…)
    choices[0].message.content The answer text
    choices[0].message.reasoning The model's thinking trace, when the model exposes one (some models use reasoning_content)
    choices[0].finish_reason stop for a clean finish; length means the token budget ran out
    usage Token counts, including completion_tokens_details.reasoning_tokens

    Every inference also returns an inference-id response header, a stable identifier for the request (also visible as x-request-id and embedded in the completion id). Log it: it is the handle for the request on the network.

  4. Next steps#