Skip to content
Download Docs
Docs / Platform / Chat completions

Chat completions

An OpenAI-compatible /v1/chat/completions and /v1/models so existing clients can talk to MaxiMind's models by changing only the base URL and key.

Base URL and auth

Base URL: https://maximind.dev/v1. Send Authorization: Bearer <MaxiMind API key> or x-api-key. The key needs the generate capability and a permitted engine. This surface never falls back to a pay-per-use API, even if the request says subscription_only: false.

List models

GET /v1/models

curl -s https://maximind.dev/v1/models -H "Authorization: Bearer $MAXIMIND_API_KEY"

Returns the allowed catalogue as OpenAI model objects. IDs are engine/model: codex/gpt-5.6-sol, claude/opus, agy/gemini-3.8-flash-high, plus auto, auto/pro and auto/fast. Denied models (Codex Astra, Claude Fable) are omitted. See Models.

Create a chat completion

POST /v1/chat/completions

curl -sN https://maximind.dev/v1/chat/completions \
  -H "Authorization: Bearer $MAXIMIND_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"claude/opus","stream":true,"messages":[{"role":"user","content":"Hello"}]}'
Name Type Required Description
model string Yes engine/model, or auto, auto/pro, auto/fast. An explicit pin rotates that engine's accounts and never switches engines. Unknown ids return 400; denied ids resolve to the engine's default.
messages array Yes Full history each turn. system and developer messages form the system prompt; user and assistant messages become the transcript. String content and text content parts are accepted; image_url parts are accepted where documented under Images below.
stream boolean No true for SSE delivery with keepalives. Recommended for Pro or long answers.
response_format object No {"type":"json_object"} asks for a JSON answer. JSON schemas are not supported.
temperature, max_tokens number No Accepted but not applied by the CLI adapter.

Send the whole message history every turn. Changing model with the same history switches models mid-conversation.

Streaming behaviour

Streaming is buffered answer delivery, not native token streaming:

  1. An SSE comment is sent immediately and another every 10 seconds while the CLI generates, so the connection never idles out.
  2. When the answer is complete it is emitted in short text chunks.
  3. A stop chunk follows, then [DONE].

Chunks report the engine and model that served the answer. Non-streaming long requests can still exceed the proxy timeout, so use streaming for Pro-class models. A client that disconnects mid-stream does not kill the already-started CLI job; it finishes and is recorded.

Both streaming and non-streaming responses disable shared caching.

What is not supported

  • Native OpenAI tools / function calling. Use a coding client's text or XML tool mode (for example Cline with nativeToolCallEnabled: false and the legacy rollout bundle); the tool instructions travel as text for the client to execute locally.
  • Audio, embeddings, text-to-speech.
  • JSON schemas (response_format with a schema).
  • Reliable usage: token counts come back as zero because the CLIs do not expose them.
  • Paid-API fallback of any kind.

Images in messages

A user message may carry {"type":"image_url","image_url":{"url":"https://…"}} parts, or a data:image/png;base64,… URL, alongside text parts; image-only user messages are accepted. The loader is the same as for generate attachments: allow-listed hosts, 10 files, 15 MiB per file, 40 MiB total, and the encoded JSON request is bounded to 60 MiB. The response carries x-maximind.attachments with per-file read receipts; when streaming it is on the final completion chunk. Choose a Google Gemini agy model or a verified Codex model for image reading. See Vision.

Size limits

Route Total characters (including system prompt)
Explicit Claude pin (claude/…) 400,000
Other engines and auto routes 100,000

Requests above these bounds fail explicitly; history is never silently truncated. Claude input is passed on stdin, in per-invocation safe mode with server-side tools and session persistence disabled. Encoded request body: 60 MiB.

Admission: 24 running model requests globally (never below 3 GB free memory) and 12 per API-key owner, shared with /api/ai/generate and /api/ai/agent. Saturated requests get 429 with Retry-After: 5.

Errors

Authentication and validation errors return OpenAI-shaped error objects with 4xx status codes.

Status Meaning
400 Unknown model id, malformed messages, request over the character limit.
401 Missing or invalid key.
403 Key lacks generate or a permitted engine.
429 Admission saturated; Retry-After: 5.
503 Capacity exhausted: no account of the pinned or chained engines could answer. Body carries sanitized account states.

After a stream has started the HTTP status cannot change: a failure arrives as an SSE error object followed by [DONE], without a successful stop chunk.

Every call is logged with surface: openai, engine, account, actual model, elapsed time and outcome.

Clients known to work

  • aichat: an openai-compatible client with base https://maximind.dev/v1, function_calling disabled.
  • Cline (VS Code): OpenAI Compatible provider, cline.rollout.bundleOverride: "legacy", nativeToolCallEnabled: false, a Claude pin for large contexts.
  • Open WebUI: sends owned image uploads as data-image parts.

For coding in a terminal on your own machine, use MaxiMind Code, which has its own credential and /api/code/v1/chat/completions with the same shape.