Chat completions

Send a list of messages to an OpenAI-compatible endpoint and get back a completion with token usage, cost, and a request id.

Endpoint

POST /v1/chat/completions is the primary inference endpoint. It is request-compatible with the OpenAI Chat Completions API, so existing clients work by changing only the base URL and key. Authenticate with a bearer token as described in Authentication.

Credits are checked before any provider call. If your organization cannot cover the estimated cost of a request, the call is rejected with insufficient_credits and no provider is contacted. See Errors for the full list.

Idempotency-Key is optional for OpenAI client compatibility. For Klara Base Preview v1, send a unique 8-200 character key and reuse it only when retrying the exact same request. This prevents a retry from reserving or dispatching paid capacity twice. When the header is omitted, the gateway returns a request-scoped generated key in x-amai-idempotency-key, but the original call does not claim cross-request replay protection.

Request

The request body is JSON. The fields you will use most:

Field	Type	Description
`model`	string	The model id to route to. Klara Base Preview v1 and v2 accept standard-scoped keys from paid workspaces whenever the selected route is available. Current wire ids, prices, and route status are on the Models page.
`messages`	array	Conversation so far. Each item has a `role` (`system`, `user`, `assistant`, or `tool`) and `content`.
`max_tokens`	integer	Upper bound on tokens generated in the completion. Lower values reduce cost. The request fails with `context_length_exceeded` if the prompt plus `max_tokens` exceeds the model context window.
`tools`	array	Optional function definitions the model may call. Pair with `tool_choice` to require, forbid, or auto-select a tool.
`reasoning_effort`	string	Use only a mode published for the selected model. Klara Base Preview routes use their qualified release defaults when this field is omitted. Unsupported values, contradictory thinking flags, raw token ids, and runtime adapters are rejected.
`temperature`	number	Optional sampling temperature. Defaults to the model's documented default.
`stream`	boolean	Set `true` to receive incremental chunks over SSE. See Streaming.

Example request

chat-completions.sh

curl https://api.advancedmind.ai/v1/chat/completions \
  -H "Authorization: Bearer $AMAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: protocol-risk-turn-20260718-01" \
  -d '{
    "model": "Klara-base-preview-v1",
    "messages": [
      { "role": "system", "content": "You are a research assistant." },
      { "role": "user", "content": "Summarize the risk model for the attached protocol." }
    ],
    "max_tokens": 1024
  }'

Response

A non-streaming response returns a single completion object. Alongside the standard OpenAI fields, every response carries an advancedmind object with the request id, the route that served the call, the access tier, and the metered cost, the same record that backs your usage and billing pages.

response.json

{
  "id": "chatcmpl_8sQ2f1Kd9vTb",
  "object": "chat.completion",
  "created": 1750636800,
  "model": "Klara-base-preview-v1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The protocol's risk model has three trust boundaries..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 318,
    "total_tokens": 730
  },
  "advancedmind": {
    "request_id": "req_b4f01c9a2e7d",
    "idempotency": {
      "key": "protocol-risk-turn-20260718-01",
      "caller_supplied": true,
      "cross_request_replay_safe": true
    },
    "public_model": "Klara-base-preview-v1",
    "provider": "advancedmind-ai",
    "route": {
      "public_model": "Klara-base-preview-v1",
      "provider": "advancedmind-ai",
      "region": "managed"
    },
    "access": {
      "tier": "standard",
      "research_mode": false
    },
    "cost": {
      "input_tokens": 412,
      "output_tokens": 318,
      "customer_charge_usd": 59.3,
      "currency": "USD"
    }
  }
}

Usage and token accounting

The usage object reports prompt_tokens, completion_tokens, and total_tokens. Cost is computed from these counts at the published input and output rates, then applies any model request minimum shown on the Preview funding & usage page before charging purchased credits — API usage is pay-as-you-go. The same figures appear under advancedmind.cost so a client can read the exact charge without a second lookup.

Request id

Every response includes advancedmind.request_id, also returned as the x-request-id response header. Record it. It is the key for tracing a call in usage and the only identifier support will ask for. Error responses carry the same id.

Reasoning content

When the selected route returns a separate reasoning channel, the response preserves it as message.reasoning_content; streaming responses use delta.reasoning_content. The final answer remains in content.

Route and access

advancedmind.route names the serving route by public_model, provider, and region. advancedmind.access records the access tier and whether a Research Mode entitlement applied to the call. Klara Base Preview v1 and v2 use the standard tier for ordinary paid access. A higher-risk Research Mode call still requires the matching active entitlement; no approval overrides a disabled, unhealthy, or stale signed release.

Tool calls

Pass tools to let the model request a function call instead of replying directly. When the model chooses a tool, the response sets finish_reason to tool_calls and returns the call in message.tool_calls. Run the tool yourself, then send the result back as a message with role: "tool" to continue the turn.

tools-request.json

{
  "model": "Klara-base-preview-v2",
  "messages": [
    { "role": "user", "content": "What is the EC50 reported for compound X in the attached assay?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_assay",
        "description": "Return assay results for a compound id.",
        "parameters": {
          "type": "object",
          "properties": {
            "compound_id": { "type": "string" }
          },
          "required": ["compound_id"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "max_tokens": 512
}

The model responds with a tool call rather than content:

tool-call.json

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_91ab",
            "type": "function",
            "function": {
              "name": "lookup_assay",
              "arguments": "{\"compound_id\":\"X-2207\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Models: the production models and how to choose between them.
Streaming: receive token deltas as they are produced.
Errors: status codes, when each occurs, and what to do.
Preview funding & usage: how token usage becomes a charge.