Create a chat completion

OpenAI-compatible chat completion. ModelBeat reserves a worst-case cost hold before routing, then settles it against realized usage after the provider responds. A `402` means the hold exceeded the available prepaid balance.

OpenAI-compatible chat completion.

ModelBeat reserves a worst-case cost hold before routing, then settles it against realized usage after the provider responds. A 402 means the hold exceeded the available prepaid balance.

Authorization

bearerAuth

AuthorizationBearer <token>

A ModelBeat API key, prefixed mb_live_, sent as Authorization: Bearer <key>.

Keys are issued in the ModelBeat console and are scoped to one tenant. The example value used throughout this document (mb_live_EXAMPLE_NOT_A_REAL_KEY_00000000000000000000) is a placeholder and will not authenticate.

In: header

Header Parameters

Idempotency-Key?string

Opaque, caller-chosen key that makes a retry safe. The OpenAI SDK — the integration path ModelBeat advertises — retries 5xx and timeouts by default; without this header each retry is a new logical request, i.e. a second reservation and a second charge for one prompt. Send the same key on a retry and ModelBeat returns the original reservation: one hold, one charge.

Reusing a key for a different request body, or one whose reservation was already settled, is refused with 409. Keys longer than 255 characters are ignored (treated as absent).

Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Either auto or an intelligence tier.

auto selects the cheapest candidate that clears the request's hard gates — output cap, context window, capabilities, and quality floor — and cost decides among what survives.

The three tiers — modelbeat-advanced, modelbeat-standard, modelbeat-fast — raise the quality floor that candidates must clear before cost decides. They name a capability band, not a model.

A specific model id cannot be named, pinned, preferred or excluded. If nothing clears the gates the request is refused with 400; it is never served by something that does not qualify.

Value in

"auto"
"modelbeat-advanced"
"modelbeat-standard"
"modelbeat-fast"

messages*array<>

Items1 <= items

max_tokens?integer

Range1 <= value

temperature?number

Range0 <= value <= 2

top_p?number

Range0 <= value <= 1

stop?string|array<string>

stream?boolean

When true, the response is streamed as server-sent events (SSE).

Defaultfalse

[key: string]?any

Response Body

`application/json`

curl -X POST "https://example.com/chat/completions" \  -H "Idempotency-Key: req-8f3a1c00-2b7e-4d9a-9c11-000000000000" \  -H "Content-Type: application/json" \  -d '{    "model": "auto",    "messages": [      {        "role": "system",        "content": "string"      }    ]  }'

{  "id": "string",  "object": "string",  "created": 0,  "model": "string",  "system_fingerprint": "string",  "choices": [    {      "index": 0,      "finish_reason": "string",      "message": {}    }  ],  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0,    "total_tokens": 0,    "cost": {      "input_tokens_cost": 0,      "output_tokens_cost": 0,      "reasoning_tokens_cost": 0,      "citation_tokens_cost": 0,      "search_queries_cost": 0,      "request_cost": 0,      "total_cost": 0    }  },  "extra_fields": {    "request_type": "string",    "routing_info": {      "level": "advanced",      "is_fallback": true,      "tier_escalated": true    },    "latency": 0,    "chunk_index": 0  }}

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

409application/json

429application/json

501application/json

503application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`