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.

Request

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

Field	Type	Description
`model`	string	The model id to route to. AMAI Meridian, AMAI Forge, and AMAI Horizon run in production; their wire ids are listed on the Models page and used in the examples below. All are standard tier, so any key with credits can call them.
`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.
`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" \
  -d '{
    "model": "amai-meridian",
    "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": "amai-meridian",
  "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",
    "route": {
      "provider": "advancedmind-ai",
      "model": "amai-meridian",
      "region": "global"
    },
    "access": {
      "tier": "standard",
      "research_mode": false
    },
    "cost": {
      "input_usd": 0.001030,
      "output_usd": 0.002544,
      "total_usd": 0.003574,
      "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 per-million input and output rates published on the Pricing & credits page, then debited from your credit balance. 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.

Route and access

advancedmind.route names the serving route, model, and region that served the request. advancedmind.access records the access tier and whether a Research Mode entitlement applied to the call. The launch models are standard tier, so research_mode is false unless your request ran inside an approved Research Mode project scope.

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": "amai-horizon",
  "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.
Pricing & credits: how token usage becomes a charge.