API Reference
API reference
Every Melious endpoint, grouped by API shape.
Three API shapes, one base URL, one API key. The OpenAI-compatible endpoints live under /v1/… with the shapes you'd expect from the OpenAI SDK. The Anthropic-compatible endpoints — /v1/messages and /v1/messages/count_tokens — accept the shapes the Anthropic SDK sends. System One — POST /v1/systemone — is a standalone JSON shape for typed decisions.
Base URL
https://api.melious.aiSend either Authorization: Bearer <KEY> or x-api-key: <KEY> — both work on every endpoint. See Authentication.
Endpoints
OpenAI-compatible
| Method | Path | What it does |
|---|---|---|
POST | /v1/chat/completions | Chat, with tools, vision, structured output, streaming |
POST | /v1/responses | Responses API — drop-in for Codex CLI and Responses API clients |
POST | /v1/embeddings | Vector embeddings from text |
POST | /v1/rerank | Reorder documents by relevance to a query |
POST | /v1/images/generations | Generate images from text |
POST | /v1/audio/transcriptions | Speech to text |
GET | /v1/models | List models |
GET | /v1/models/{id} | Retrieve one model |
Anthropic-compatible
| Method | Path | What it does |
|---|---|---|
POST | /v1/messages | Chat in the Messages API shape |
POST | /v1/messages/count_tokens | Preflight token count |
System One
| Method | Path | What it does |
|---|---|---|
POST | /v1/systemone | Typed choice, score, and noul decisions |
Batch
| Method | Path | What it does |
|---|---|---|
POST | /v1/batches | Create an asynchronous batch job |
GET | /v1/batches | List batches |
GET | /v1/batches/{id} | Retrieve a batch |
POST | /v1/batches/{id}/cancel | Cancel a batch |
POST | /v1/files | Upload a batch input file |
GET | /v1/files | List uploaded files |
GET | /v1/files/{id} | Retrieve file metadata |
GET | /v1/files/{id}/content | Download raw file content |
DELETE | /v1/files/{id} | Delete a file |
Vector stores
| Method | Path | What it does |
|---|---|---|
POST | /v1/vector_stores | Create a store |
GET | /v1/vector_stores | List stores |
GET | /v1/vector_stores/{id} | Retrieve a store |
POST | /v1/vector_stores/{id} | Update a store |
DELETE | /v1/vector_stores/{id} | Delete a store |
POST | /v1/vector_stores/{id}/files | Attach a file |
POST | /v1/vector_stores/{id}/search | Semantic search |
Tools and MCP endpoints (/v1/tools, /v1/mcp, /v1/documents/convert) have their own section — see Tools.
What inference responses carry
Two Melious-specific objects ride on Chat completions, Embeddings, and Rerank responses. Chat completions streams carry them on the final usage chunk unless you set stream_options.include_usage to false:
{
"environment_impact": {
"energy_kwh": 0.00015,
"carbon_g_co2": 0.06,
"water_liters": 0.0002,
"renewable_percent": 85,
"pue": 1.18,
"provider_id": "ovhcloud",
"location": "FR"
},
"billing_cost": {
"energy": "0.0008",
"credits": "0.0",
"paid_with": "energy"
}
}SDKs that don't know these fields ignore them, so nothing breaks — but the data is there when you want it. environment_impact can be omitted while billing_cost is present; streams have further cases — see Streaming. Responses and Messages carry neither field, streamed or not. System One responses carry neither: a decision body holds model, answers, and usage only. See Environmental impact and Pricing.
Errors
The error shape depends on the endpoint. The OpenAI- and Anthropic-compatible endpoints each have their respective error shape, described in Errors. System One has its own envelope with lowercase codes and an X-System-One-Error-Code header — see System One.