Chat completions

POST /v1/chat/completions — OpenAI-compatible chat inference.

Models

List the models that are routable right now.

Headers

Request and response headers, including the Malibu-specific ones.

Usage object

Token counts, cached prompt tokens, daily quota.

Network stats

Public pool, routability, and status snapshots.

The primary buyer endpoint. The request and response shapes follow OpenAI’s chat completions API. Malibu adds a sticky-conversation request header, a provider-attribution response header, and a signed receipt header. Two translation facades share the same routing, quota, and settlement path: Responses (POST /v1/responses) and Anthropic Messages (POST /v1/messages).

Endpoint

POST https://api.malibu.tech/v1/chat/completions
Authorization: Bearer <MALIBU_API_KEY>
Content-Type: application/json

Request body

Standard OpenAI shape:

{
  "model": "mlx-community/Llama-3.2-3B-Instruct-4bit",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7,
  "max_tokens": 512,
  "stream": false
}

Accepted fields:

Field	Notes
`model`	Required. An `id` from `/v1/models`. Matching is case-insensitive.
`messages`	Required. OpenAI shape, including assistant `tool_calls` and `role: "tool"` results.
`max_tokens`	Per-request cap. Values above the gateway limit (currently 4,096) are rejected with `400 max_tokens_exceeded`, not clamped.
`temperature`, `top_p`	Forwarded to the provider.
`n`	Accepted for SDK compatibility. Must be `1`; anything else returns `400 n_must_be_1`.
`stream`, `stream_options`	`stream: true` for SSE. The final `usage` chunk is always sent; `stream_options` is accepted for SDK compatibility.
`stop`	Forwarded to the provider.
`presence_penalty`, `frequency_penalty`	Forwarded to the provider.
`seed`	Best effort. Not guaranteed to be deterministic across providers.
`user`	Forwarded. Opaque to Malibu.
`tools` / `tool_choice`	See Tool calling.
`response_format`	`json_schema` or `json_object`. See Structured output.
`logprobs`	Forwarded. Providers may ignore it, and behavior depends on the model.

Content shape. system and user messages accept a string or a text-only content array ([{"type": "text", "text": "..."}]). The gateway flattens text-only arrays into one string. Image, audio, and other non-text parts are rejected with 400 unsupported_content_shape. Tool-call IDs. Clients that send non-OpenAI tool-call IDs (toolu_*, UUIDs, namespaced IDs) are supported. The gateway rewrites them to a deterministic call_… form before routing and keeps each assistant tool_calls[].id paired with its tool_call_id result. Body size. Request bodies are capped at 1 MiB.

Request headers

Header	Purpose
`Authorization: Bearer <MALIBU_API_KEY>`	Required. Keys start with `mp_`.
`X-MacProvider-Conversation`	Optional sticky-conversation tag. See Sticky conversations.
`Idempotency-Key`	Optional. Resending the same key and body returns `409 idempotency_key_replayed` (the original response is not replayed). The same key with a different body returns `409 idempotency_key_body_mismatch`.
`X-Request-ID`	Optional UUID v4. If you omit it, the gateway assigns one. Reusing an ID that was already used returns `409 duplicate_request_id`.

Full reference: Headers.

Response body

Standard OpenAI shape. This is a live response from 23 Sep 2026, trimmed:

{
  "id": "chatcmpl-2dce28edf2e049beb55f9315bdf0dd6d",
  "object": "chat.completion",
  "created": 1790138407,
  "model": "mlx-community/Llama-3.2-3B-Instruct-4bit",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Hi!"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 39,
    "completion_tokens": 2,
    "total_tokens": 41,
    "cached_prompt_tokens": 0,
    "prompt_tokens_details": {"cached_tokens": 0}
  }
}

See Usage object for the cache fields.

Response headers

Header	Purpose
`X-Request-ID`	Request identifier. Include it in bug reports and use it to look up receipt metadata.
`X-Provider-Id`	Opaque ID of the provider Mac that served the request.
`X-MacProvider-Receipt`	v0.3 Ed25519-signed receipt on some non-streaming responses (currently roughly a quarter to a third). Never on streams. For the rest, use `GET /v1/receipts`.
`X-MacProvider-Streaming-Mode`	Streaming responses only: `incremental`, `buffered_kill_switch`, or `buffered_provider_downgrade`.
`X-RateLimit-Limit` / `-Remaining` / `-Reset`	Daily token quota for your account. `-Reset` is a Unix timestamp.
`X-RateLimit-Limit-Requests` / `-Remaining-Requests`	Per-account concurrency (requests in flight).

Full reference: Headers.

Streaming

Set stream: true and read Server-Sent Events. Each data: line carries an OpenAI chat.completion.chunk:

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}],...}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"By"}}],...}
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],...}
data: {"object":"chat.completion.chunk","choices":[],"usage":{...}}
data: [DONE]

The final usage chunk is always sent, whether or not you set stream_options.include_usage. Streaming responses never carry a receipt header. Some non-streaming responses do; for the rest, use GET /v1/receipts. See Signed receipts. If the provider disconnects after the first event has reached you, the stream ends with a provider_disconnected error event. A retry is a new, separately metered request. Failover to another provider happens only before any bytes have been sent.

Errors

Errors use OpenAI’s envelope plus a retryable boolean:

{
  "error": {
    "message": "No provider has advertised the requested model",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": null,
    "retryable": false
  }
}

Honor retryable. When it is true, the same request can succeed later without changes, and Retry-After or X-RateLimit-Reset* headers tell you how long to wait.

Status	Common `code` values
400	`invalid_request`, `max_tokens_exceeded`, `n_must_be_1`, `unsupported_content_shape`, `invalid_conversation_tag`, `ambiguous_credentials`
401	`missing_bearer_token`, `invalid_api_key`
403	`api_key_revoked`, `account_blocked`
404	`model_not_found`: no connected provider advertises that model
409	`duplicate_request_id`, `idempotency_key_replayed`, `idempotency_key_body_mismatch`
413	`request_too_large`
429	`quota_exhausted` (daily token quota), `account_request_rate_exceeded`, `account_concurrency_exceeded`, `provisional_quota_exceeded` (every eligible provider is a provisional provider that has used its quota)
502	`upstream_provider_error`, `invalid_provider_response` (retryable)
503	`no_provider_available` (the model is known but no slot freed within the short queue window), `public_api_paused`
504	`provider_timeout`

Streaming errors after headers are sent arrive as an SSE data: frame that holds the same error object, followed by data: [DONE].

Litepaper

Getting started

Buyers

Providers

Network & trust

Guides index

Ledger

Chat completions

Chat completions

Models

Headers

Usage object

Network stats

Endpoint

Request body

Request headers

Response body

Response headers

Streaming

Errors

​Chat completions

Models

Headers

Usage object

Network stats

​Endpoint

​Request body

​Request headers

​Response body

​Response headers

​Streaming

​Errors

Chat completions

Endpoint

Request body

Request headers

Response body

Response headers

Streaming

Errors