Modellix LLM API Guide

Modellix LLM is a text gateway at https://llm.modellix.ai with three protocol surfaces:

Protocol	Method	Path	Typical clients
Chat Completions	`POST`	`/v1/chat/completions`	OpenAI SDK, Codex, Cursor, most chat clients
Responses	`POST`	`/v1/responses`	OpenAI Responses API clients
Messages	`POST`	`/v1/messages`	Anthropic SDK, Claude Code

Also available on the same host: GET /v1/models and GET /v1/logs. Calls are synchronous (optional streaming SSE). Request and response shapes follow the corresponding official protocols; this guide lists core fields only. Full OpenAPI specs: Chat Completions, Responses, Messages, List models, Request logs.

Media generation (image, video, speech) uses https://api.modellix.ai and async tasks. Do not mix that host with the LLM gateway.

Base URL and Auth

Item	Value
Host	`https://llm.modellix.ai`
Path prefix	`/v1`
Auth	`Authorization: Bearer <Modellix API Key>` or `x-api-key: <Modellix API Key>`

Authorization: Bearer mdlx-xxxxxxxx

x-api-key: mdlx-xxxxxxxx

Both headers are equivalent. If both are sent, they must be the same key. Get a key from the console—not a vendor platform key.

Header style	Typical clients
Bearer	OpenAI SDK, Codex, OpenCode, Cursor
`x-api-key`	Anthropic SDK, Claude Code

Models

Pass model in the JSON body as provider/name. See Models & Pricing for the full Model ID list and rates. Availability follows the console and product releases. You can also list currently available Model IDs via GET /v1/models.

Choose a Protocol

The three endpoints use different URLs and body shapes. Do not mix fields across protocols.

	Chat Completions	Responses	Messages
Input	`messages: [{role, content}, ...]`	`input` (string or content array)	Anthropic `messages` + optional `system`
Length	`max_tokens` / `max_completion_tokens`	`max_output_tokens`	`max_tokens` (required)
Stream	`stream: true` → OpenAI chat.completion.chunk SSE	`stream: true` → Responses SSE	`stream: true` → Anthropic Messages SSE

Routing tips

Model prefix	Recommended protocol
`openai/...`	Chat Completions or Responses
`anthropic/...`	Messages (Anthropic clients); Chat Completions also works for many tools
`google/...`	Chat Completions (Responses also fine)

Chat Completions

POST /v1/chat/completions
Authorization: Bearer <API_KEY>
Content-Type: application/json

Field	Required	Description
`model`	Yes	Model ID
`messages`	Yes	OpenAI-style messages
`stream`	No	Default `false`; `true` returns SSE
`max_tokens`	No	Generation cap (model-dependent)
`max_completion_tokens`	No	Preferred cap on some newer OpenAI-style models
`temperature`	No	Sampling temperature
`n`	No	Number of choices

curl -sS "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "stream": false,
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
  }'

Streaming:

curl -sS -N "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "stream": true,
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "ping"}]
  }'

See Create chat completion.

Responses

POST /v1/responses
Authorization: Bearer <API_KEY>
Content-Type: application/json

Field	Required	Description
`model`	Yes	Model ID
`input`	Yes	String or content array (not Chat Completions `messages`)
`stream`	No	Default `false`
`max_output_tokens`	No	Output cap
`temperature`	No	Sampling temperature

curl -sS "https://llm.modellix.ai/v1/responses" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-luna",
    "stream": false,
    "max_output_tokens": 256,
    "input": "Introduce yourself in one sentence"
  }'

See Create response.

Messages (Anthropic)

POST /v1/messages
Authorization: Bearer <API_KEY>
Content-Type: application/json

Field	Required	Description
`model`	Yes	For example `anthropic/claude-sonnet-5`
`messages`	Yes	Anthropic messages (`user` / `assistant` only)
`max_tokens`	Yes	Output cap
`stream`	No	Default `false`
`system`	No	System prompt (string or content blocks)

Auth may use Bearer or x-api-key. Optional anthropic-version header is forwarded when present.

curl -sS "https://llm.modellix.ai/v1/messages" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "ping"}]
  }'

See Create message.

Session Header

For multi-turn session affinity, send:

Header	Rules
`X-Mdlx-Session-Id`	Length 8–128; alphanumeric, `-`, and `_` only

Some native tools send their own session header (for example Claude Code’s X-Claude-Code-Session-Id). If both are present, X-Mdlx-Session-Id takes precedence.

curl -sS "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Mdlx-Session-Id: my-conversation-001" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Continue our previous topic"}]
  }'

End-User ID Header

Optional. Tag requests with your own end-user identifier so you can filter request logs later. Invalid values return 400.

Header	Rules
`X-Mdlx-User-Id`	Optional; length 8–128; ASCII letters, digits, `-`, and `_` only

curl -sS "https://llm.modellix.ai/v1/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Mdlx-Session-Id: my-conversation-001" \
  -H "X-Mdlx-User-Id: end_user_01" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [{"role": "user", "content": "Continue our previous topic"}]
  }'

List Models

GET /v1/models
Authorization: Bearer <API_KEY>

Returns an OpenAI-compatible model list for the gateway (object: list, data[].id in provider/name form). IDs are de-duplicated. This endpoint uses the query rate limit (shared with request-log listing and similar read APIs)—not the inference RPM quota.

curl -sS "https://llm.modellix.ai/v1/models" \
  -H "Authorization: Bearer ${API_KEY}"

Example response:

{
  "object": "list",
  "data": [
    { "id": "openai/gpt-5.5", "object": "model" },
    { "id": "openai/gpt-5.6-sol", "object": "model" }
  ]
}

Request Logs

GET /v1/logs
Authorization: Bearer <API_KEY>

Lists your team’s LLM request logs for a time window (same API Key / team scope as inference). Uses the query rate limit.

Query	Required	Description
`start_time`	Yes	UNIX seconds
`end_time`	Yes	UNIX seconds; must be greater than `start_time`; span ≤ 30 days
`mdlx_user_id`	No	Exact match; same rules as `X-Mdlx-User-Id`
`page`	No	Default `1`
`page_size`	No	Default `10`, max `100`

Response shape (fields useful for debugging and auditing):

Field	Description
`requests`	Log items
`total` / `page` / `page_size`	Pagination
`requests[].task_id`	Request id
`requests[].status` / `error`	Outcome
`requests[].model`	`{ provider, model_name }`
`requests[].prompt_tokens` / `completion_tokens` / `cached_tokens`	Token usage when available
`requests[].cost`	Cost in the console’s billing unit
`requests[].created_at`	UNIX seconds
`requests[].input` / `result`	Request/response payloads when retained

The list response does not include a mdlx_user_id field; filter with the query parameter instead.

curl -sS "https://llm.modellix.ai/v1/logs?start_time=1700000000&end_time=1700086400&page=1&page_size=20" \
  -H "Authorization: Bearer ${API_KEY}"

For media (image/video/speech) request logs on https://api.modellix.ai, see List media request logs.

Success Responses

Non-streaming: HTTP 200 with a JSON body matching the protocol (chat.completion, response, or message).
Streaming: HTTP 200, Content-Type: text/event-stream, protocol-specific SSE events.

Responses usually include usage (often on the final stream event). Billing uses token usage; see Billing.

Errors

{
  "error": {
    "message": "...",
    "type": "invalid_request_error"
  }
}

Optional fields may include code and param.

HTTP	Meaning	Common `error.type`
`400`	Invalid parameters	`invalid_request_error`
`401`	Missing/invalid key or conflicting auth headers	`invalid_request_error`
`402`	Insufficient balance	`insufficient_quota`
`404`	Unknown path or model unavailable	`invalid_request_error`
`429`	Rate limit or model temporarily unavailable	`rate_limit_exceeded` / `request_limited` / `api_error`
`5xx`	Temporary upstream or service error	`api_error`

Billing

Successful responses are billed from token usage. Unit prices and final charges follow the console and account invoice. Insufficient balance returns 402 with insufficient_quota.

Rate Limits

Case	HTTP	Common `error.type`	Notes
Inference RPM exceeded	`429`	`rate_limit_exceeded`	Chat / Responses / Messages; may include `X-RateLimit-Limit` / `Remaining` / `Reset`
Query RPM exceeded	`429`	`rate_limit_exceeded`	`GET /v1/models`, `GET /v1/logs` (and similar listing APIs); separate from inference RPM; same rate-limit headers
Other request limits	`429`	`request_limited`	Slow down or retry later
Model temporarily unavailable	`429`	`api_error`	May include `Retry-After`; switch model or retry

Back off and reduce request rate after 429.

Client Quick Reference

Client	Base URL	Credential env	Model prefix
OpenAI SDK	`https://llm.modellix.ai/v1`	`OPENAI_API_KEY`	`openai/...`
Codex	`openai_base_url` = `.../v1`	`OPENAI_API_KEY`	`openai/...`
Cursor	`https://llm.modellix.ai/v1`	Modellix API Key in settings	`provider/name`
Anthropic SDK / Claude Code	`https://llm.modellix.ai` (no `/v1`)	`ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN`	`anthropic/...`
OpenCode	Provider `baseURL`	`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`	Match the protocol

Google models (google/...) on the OpenAI-compatible path use OPENAI_* and the /v1 base URL.

Differences from Vendor Docs

Topic	Modellix
Auth	Bearer or `x-api-key` with a Modellix key
`model`	`provider/name` form — see Models & Pricing
Chat vs Responses	Different bodies—changing only the URL is not enough
Session	Optional `X-Mdlx-Session-Id`
End-user id	Optional `X-Mdlx-User-Id` for log filtering
Model list	`GET /v1/models` (OpenAI-compatible)
Request logs	`GET /v1/logs` (team-scoped; optional `mdlx_user_id`)

Official field catalogs: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages.

Get Started

API

Agent

SDK

Framework

IDE

Tool

Modellix LLM API Guide

Base URL and Auth

Models

Choose a Protocol

Chat Completions

Responses

Messages (Anthropic)

Session Header

End-User ID Header

List Models

Request Logs

Success Responses

Errors

Billing

Rate Limits

Client Quick Reference

Differences from Vendor Docs

​Base URL and Auth

​Models

​Choose a Protocol

​Chat Completions

​Responses

​Messages (Anthropic)

​Session Header

​End-User ID Header

​List Models

​Request Logs

​Success Responses

​Errors

​Billing

​Rate Limits

​Client Quick Reference

​Differences from Vendor Docs

Base URL and Auth

Models

Choose a Protocol

Chat Completions

Responses

Messages (Anthropic)

Session Header

End-User ID Header

List Models

Request Logs

Success Responses

Errors

Billing

Rate Limits

Client Quick Reference

Differences from Vendor Docs