中文 Log in Get started
Documentation

The whole API fits
on one page.

1AI Cloud speaks the OpenAI wire format. If you have called an OpenAI-compatible endpoint before, everything below will already look familiar — which is the point.

Base URL and authentication

Send your key as a bearer token. Never put it in a query string, and never ship it in client-side code.

auth
Base URL   https://api.1ai.cloud/v1
Header     Authorization: Bearer $ONEAI_API_KEY
Header     Content-Type: application/json

Chat completions

The endpoint you will use for almost everything. model takes any id from the catalogue.

POST /v1/chat/completions
curl https://api.1ai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "system", "content": "You are terse."},
      {"role": "user",   "content": "Say hello in one sentence."}
    ],
    "temperature": 0.7,
    "stream": false
  }'

Streaming

Set stream: true to receive server-sent events. The stream terminates with data: [DONE], exactly as the OpenAI SDKs expect.

stream.py
stream = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Listing models

Returns everything your key can currently route to. Useful as a health check in CI.

GET /v1/models
curl https://api.1ai.cloud/v1/models \
  -H "Authorization: Bearer $ONEAI_API_KEY"

Fallbacks

Pass an ordered list of alternates. If the primary upstream returns a rate limit, a timeout or a 5xx, the request moves down the list within the same call.

fallbacks.json
{
  "model": "claude-sonnet-5",
  "fallbacks": ["gpt-5.4", "glm-5.2", "kimi-k3"],
  "messages": [{"role": "user", "content": "..."}]
}

Errors

StatusWhat to do
401Key missing, malformed or revoked. Check the Authorization header.
402Balance exhausted. Top up in the console.
404Unknown model id. Call GET /v1/models to see what your key can route to.
429Rate limited upstream. Back off, or declare a fallback list so the call reroutes instead.
5xxUpstream failure. Safe to retry with backoff; a fallback list handles this for you.

Practical notes

  • Issue one key per environment. Revoking a leaked staging key should never touch production traffic.
  • Keep the system prompt and tool definitions byte-identical between turns — that is what makes cache-hit pricing apply.
  • Set an explicit timeout in your client. The default in most SDKs is longer than any user will wait.
  • Pin a model id rather than an alias if reproducibility matters more to you than automatically getting the newest version.
Need something not covered here — batch jobs, embeddings, a dedicated region, or a data-handling review? and we will answer with specifics rather than a brochure.