Chat API

Status: Available — POST /v1/chat/completions.

Endpoint

POST https://api.beatra.ai/v1/chat/completions

Request

POST /v1/chat/completions
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <uuid>

{
  "model": "auto",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "Say hi in five words." }
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 256
}

Key fields

Field	Type	Required	Notes
`model`	string	yes	`"auto"` or an account-enabled model id.
`messages`	array	yes	Each item has `role` (`system` / `user` / `assistant`) and `content` (string).
`stream`	boolean	no	When `true`, response is `text/event-stream` ending with `data: [DONE]`.
`temperature`	number	no	`0.0`–`2.0`. Lower = more deterministic.
`max_tokens`	integer	no	Cap on response length. Combined input + output may also be capped by the model.
`top_p`	number	no	Nucleus sampling. Pass either `temperature` or `top_p`, not both.

Response (sync)

{
  "id": "chatcmpl_01J5...",
  "model": "<resolved model id>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hi there my friend!" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 6,
    "total_tokens": 30
  }
}

Store model and the X-Request-Id response header alongside your job record.

Response (stream)

With "stream": true, the response is text/event-stream:

data: {"choices":[{"delta":{"role":"assistant"}}]}

data: {"choices":[{"delta":{"content":"Hi"}}]}

data: {"choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Treat any disconnect before data: [DONE] as an incomplete response. See Sync vs streaming in Concepts.

Errors

Use the standard error envelope. Most common for this endpoint:

invalid_request (400) — body failed validation; details lists fields
rate_limited (429) — back off and retry with the same Idempotency-Key
model_unavailable (503) — switch to another model id or retry with "auto"

Operation page

Create chat completion

POST /v1/chat/completions — generated from OpenAPI

Chat API

Create chat completion

On this page