# API Guide

Use every Milly Lab model from your own code — in any language, on any platform, from a server or a browser — through an OpenAI-compatible API that bills through your Milly Lab account. This guide covers the first request, SDK setup, streaming, live pricing, the billing rules, per-key controls, rate limits, error codes and the usage endpoint.

Last updated: 2026-10-24 · <https://m-lab.app/en/docs/api>

---

## Base URL

```
https://api.m-lab.app/v1
```

Every endpoint below is relative to this base. This guide is the reference for the public API; Milly Lab does not publish an OpenAPI schema.

---

## Quickstart

1. **Create a key.** Open the web app → Settings → *Security* → *API keys* (the **Manage API keys** button on the API page goes there too) and choose **Open API keys**. The API keys page of the Full Console opens; choose *Create key* there. API access is included in **Max** and higher plans. The raw key (`mk_…`) is shown once; only its last four characters are stored.
2. **Point an OpenAI SDK at the base URL.** Any client that speaks the OpenAI chat-completions protocol works with a base-URL change.
3. **Pick a model** from `GET /v1/models` and send your first request.

```bash
curl https://api.m-lab.app/v1/chat/completions \
  -H "Authorization: Bearer $MILLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5",
       "messages": [{"role": "user", "content": "Three facts about Dushanbe."}]}'
```

The response is a standard `chat.completion` object with `choices[0].message.content` and `usage` (the tokens you were billed for).

---

## SDK setup

### Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.m-lab.app/v1",
    api_key="mk_...",
)

r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Three facts about Dushanbe."}],
)
print(r.choices[0].message.content, r.usage)
```

### Node.js

```js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.m-lab.app/v1",
  apiKey: process.env.MILLY_API_KEY,
});

const r = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [{ role: "user", content: "Three facts about Dushanbe." }],
});
console.log(r.choices[0].message.content, r.usage);
```

### Plain fetch (any runtime)

```js
const res = await fetch("https://api.m-lab.app/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: "Bearer " + MILLY_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "claude-sonnet-5",
    messages: [{ role: "user", content: "Three facts about Dushanbe." }] }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
```

Supported request fields: `model`, `messages` (roles `system`/`developer`, `user`, `assistant`; string content or `text` parts; on models whose `capabilities.vision` is true, also `image_url` parts — a `data:` or `https:` URL to a PNG, JPEG, GIF or WebP image up to 5 MB, at most 8 per request), `stream`, `max_tokens` / `max_completion_tokens`, `reasoning_effort` (`low` · `medium` · `high`). Sampling fields (`temperature`, `top_p`, …) are accepted for compatibility; the platform router decides sampling. `tools`, `tool_choice` and tool/function messages are accepted but **not executed yet** — see *Coming next*.

---

## Streaming

Set `stream: true` to receive server-sent events. Each event is a `chat.completion.chunk`; the final chunk carries `finish_reason` and `usage`, then `data: [DONE]`. While the model thinks before it writes, the stream sends a comment line (`: keepalive`) every few seconds so proxies and clients keep the connection open; SSE clients, the OpenAI SDKs included, skip such lines.

If the model fails mid-answer, the answer is never passed off as complete: a stream sends an `error` event (code `upstream_interrupted`; the OpenAI SDKs raise on it) and its final chunk has `finish_reason: "error"`; a non-streaming call answers `502 upstream_interrupted` with what the model wrote so far in `error.partial_content` and the `usage` it was billed for, plus `x-should-retry: false`, so an SDK does not re-run the call on its own.

```python
stream = client.chat.completions.create(model="claude-sonnet-5", stream=True,
    messages=[{"role": "user", "content": "Write a haiku about mountains."}])
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\n", chunk.usage)
```

If your client disconnects mid-stream, generation still runs to completion on the platform and the tokens produced are billed.

---

## Models and live pricing

`GET /v1/models` is public (no key required) and returns every API-enabled model with one price per unit: what a call costs when it is paid from your balance.

```json
{
  "id": "claude-sonnet-5",
  "display_name": "Claude Sonnet 5.5",
  "modality": "chat",
  "capabilities": { "vision": true, "tools": false, "streaming": true },
  "context_window": 1000000,
  "max_output_tokens": 64000,
  "pricing": {
    "unit": "per_1m_tokens",
    "input_per_1m_usd": 6.0,
    "output_per_1m_usd": 22.0,
    "cache_write_5m_per_1m_usd": 7.5,
    "cache_write_1h_per_1m_usd": 12.0,
    "cache_read_per_1m_usd": 0.3,
    "web_search_per_request_usd": 0.02
  }
}
```

Claude rows also list the prices of prompt-cache tokens — `cache_write_5m_per_1m_usd`, `cache_write_1h_per_1m_usd` and `cache_read_per_1m_usd`, per 1M tokens — and `web_search_per_request_usd`, the price of one web search. A model with a second price for long prompts carries `long_context`; Claude Haiku 5.5 lists `{"threshold_prompt_tokens": 100000, "input_per_1m_usd": 3.0, "output_per_1m_usd": 7.0, "cache_write_5m_per_1m_usd": 3.75, "cache_write_1h_per_1m_usd": 6.0, "cache_read_per_1m_usd": 0.3}`. The OpenAI rows list `cache_write_30m_per_1m_usd` and `cache_read_per_1m_usd`. The Grok row lists `web_search_per_request_usd` too while Grok runs its own web search. *Billing rules* below says how each one applies.

Image models carry `pricing.unit = "per_image"` with `per_image_usd`, the price of one image at standard quality, and `per_quality_usd`, the price of one image at each quality the model takes (for example `{"low": …, "standard": …, "high": …}`) — exactly what a call at that quality is charged from the balance. The embeddings model is listed under `modality: "embedding"`. When you call `/v1/models` **with** a key, each row also carries `allowed_for_key` — whether that key may call the model — and `included_in_plan` — whether the account's plan allocates the model (allowance first) or every call is paid from the balance; the top-level `plan` names the plan. On a $0 balance, a model that is not included answers 402 from the first token.

Only listed models are callable. A retired key with no successor (`gpt-5.4-mini`) answers **404** `model_not_found`; a legacy alias that points at a current model (`claude-sonnet` → `claude-sonnet-5`, `claude-haiku-4-5` → `claude-haiku-5-5`, `gpt-4o` → `gpt-5.4-nano`) still resolves and is billed at the listed rate of the model that serves it.

The live table on the **API** page inside the web app renders this endpoint.

---

## Billing rules

1. **Plan first.** If your plan includes the model, its monthly allowance for that model covers the request first.
2. **Then balance.** Anything the allowance does not cover is paid from your top-up balance: tokens × the model's **listed price** (`input_per_1m_usd` and `output_per_1m_usd`; images: the `per_quality_usd` price of the quality you ask for, per image (`per_image_usd` without `quality`); embeddings: the listed price per 1M input tokens), plus the long-prompt, prompt-cache and web-search prices below when they apply. The API model list and the Developers page show every price.
3. **Usage shows what each request cost.** `GET /v1/usage` counts every request at its listed price, whether your plan's allowance or your balance paid for it; Settings → *Billing* shows what your balance paid.
4. **Reserve before spend.** A request that cannot be covered by remaining allowance plus balance is refused with **402** *before* any provider call; the platform holds the worst-case amount during generation and settles to the real usage afterwards. If the model's provider is not configured on the deployment, the answer is **503** `provider_unavailable` — also before any hold, so nothing is billed. A provider that fails before producing output is **502** with nothing billed; output that did stream before a failure is billed.
5. **Per-key controls** (below) add a spend cap and a model allow-list on top of the account-level rules.

Every API request writes a usage row tagged with the key that made it; those rows drive Settings → *Billing*, the per-key *spent this month* figure and `GET /v1/usage`.

### Long prompts, prompt caching and web search

Each of these has its own listed price on the model's row in `GET /v1/models`, and the response's `usage` carries the counts it applies to:

- **Long prompts.** A request whose prompt — `usage.prompt_tokens`, every input token, cached ones included — exceeds `pricing.long_context.threshold_prompt_tokens` is billed entirely at the `long_context` prices. Claude Haiku 5.5: up to 100,000 prompt tokens, $2.20 per 1M input and $3.00 per 1M output tokens; above that, $3.00 and $7.00. The OpenAI models (above 272,000 prompt tokens) and Grok (from 200,000, listed as above 199,999) have a second price too; each model's row lists its own. Each request of a tool loop is priced on its own prompt.
- **Prompt caching (Claude).** Claude keeps repeated prompt prefixes in a cache. Of the prompt tokens, those written to the cache (`usage.prompt_tokens_details.cache_write_tokens`, of which `cache_write_1h_tokens` were written for one hour) are billed at `cache_write_5m_per_1m_usd` (one-hour writes: `cache_write_1h_per_1m_usd`), those read from it (`usage.prompt_tokens_details.cached_tokens`) at `cache_read_per_1m_usd`, and the rest at `input_per_1m_usd`. On a long prompt, the three cache prices inside `long_context` apply.
- **Prompt caching (OpenAI).** The OpenAI models cache repeated prompt prefixes automatically. Of the prompt tokens, those written to the cache (`usage.prompt_tokens_details.cache_write_tokens`, kept for 30 minutes) are billed at `cache_write_30m_per_1m_usd`, those read from it (`usage.prompt_tokens_details.cached_tokens`) at `cache_read_per_1m_usd`, and the rest at `input_per_1m_usd`. On a long prompt, the two cache prices inside `long_context` apply.
- **Web search (Claude, Grok).** Each web search the model runs to answer (`usage.web_search_requests`) adds the row's `web_search_per_request_usd` (Claude $0.02, Grok $0.01).
- **Rounding.** Each request's charge is rounded to $0.000001, so a total you compute from the listed prices can differ from it by a few millionths of a dollar.

---

## Per-key controls

Set on creation or later on the API keys page of the Full Console (Settings → *Security* → *API keys* → *Open API keys*), or with `PATCH /api/keys/{id}` from your web session:

| Control | Behaviour |
|---|---|
| **Monthly spend cap** (USD, whole cents — `0.05`, not `0.001`; a finer value is refused with 422) | Once the key's month-to-date spend (every request at its listed price, whether your plan's allowance or your balance paid) reaches the cap, further calls return **402** `spend_cap_reached`. The request that crosses the line still completes (its cost is unknown until it ends), so the overshoot is at most one request. Resets on the 1st of each month (UTC). |
| **Allowed models** | A list of catalog keys. Any other model returns **403** `model_not_allowed`. Empty = every API model. Legacy aliases are resolved to their current key. |

Use both on any key that leaves your own infrastructure.

---

## Embeddings

`POST /v1/embeddings` — OpenAI-compatible. Model `text-embedding-3-small` (1536 dimensions). `input` is a string or a list of up to 256 strings (12,000 characters each). Billed on input tokens; embeddings are not part of any plan allowance, so they are always paid from the balance. `encoding_format` is `float` (default) or `base64` (little-endian float32 — what the official SDKs request by default, so `client.embeddings.create(...)` works unmodified).

```python
emb = client.embeddings.create(model="text-embedding-3-small", input=["Milly Lab", "public API"])
print(len(emb.data[0].embedding), emb.usage.prompt_tokens)
```

---

## Images

`POST /v1/images/generations` — OpenAI-compatible request and response. `model` is an image key from `/v1/models` (`gpt-image-2`, `gemini-nano-banana`, `fal-ai/flux-pro`, `fal-ai/stable-diffusion-xl`), `n` 1–4, `size` `1024x1024` · `1536x1024` · `1024x1536` (mapped to the model's nearest aspect ratio), `quality` `low` · `standard` · `high` (`medium`/`hd` accepted). The call is synchronous (up to 180 s) and returns hosted `url`s; `usage.billed_usd` is what was charged to your balance (0 when your plan's allowance covered the images).

```python
img = client.images.generate(model="gpt-image-2", prompt="A watercolor map of the Pamirs", size="1024x1024")
print(img.data[0].url)
```

Images produced through the API are not added to the Light Studio history.

---

## Usage endpoint

`GET /v1/usage?from=YYYY-MM-DD&to=YYYY-MM-DD[&key=<id>]` returns requests, tokens and **spend at listed prices** (every request at its listed price, whether your plan's allowance or your balance paid). Called with an unrestricted key (no allowed models, no spend cap) it covers **every key on the account** — so one reporting key can watch a fleet (`scope: "account"`). A restricted key — allowed models or a spend cap set, as recommended for keys that may be seen, such as keys in browser code — sees **only its own usage** (`scope: "key"`), and `key=` naming another key answers 404. Default range is month-to-date; the maximum is 92 days. Web-app chat is never included. `tokens_in` counts every input token, cached ones included — the same count as a response's `usage.prompt_tokens`.

```json
{
  "object": "usage",
  "from": "2026-09-01T00:00:00", "to": "2026-09-10T12:00:00",
  "totals": { "requests": 412, "tokens_in": 1830000, "tokens_out": 210000, "usd": 12.41 },
  "by_key": [{ "key_id": "…", "name": "prod", "hint": "a1b2", "requests": 400, "usd": 12.10 }],
  "by_model": [{ "model": "claude-sonnet-5", "requests": 300, "usd": 10.20 }]
}
```

---

## Rate limits

| Limit | Value |
|---|---|
| Requests per key | 120 per minute → **429** `rate_limit_exceeded` with `Retry-After` (seconds) |
| Active keys per account | 5 |
| Messages per request | 200 |
| Characters per request | 400,000 |
| Embedding inputs per call | 256 × 12,000 characters |
| Images per call | 4 |

Every `/v1` response carries `x-request-id` (`req_…`; quote it when you write to support — it is the call's own id, logged with the call and stored with its usage, and a chat completion's `id` carries the same characters) and, once a key is authenticated, `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-window` (seconds). A 429 adds `Retry-After` — wait that many seconds, then retry. Do not retry a 402 without changing something (top up, raise the cap, pick a cheaper model).

---

## Error codes

Every error is OpenAI-shaped: `{"error": {"message": "…", "type": "…", "code": "…"}}` — branch on `code`.

| HTTP | `code` | Meaning |
|---|---|---|
| 400 | `invalid_body` · `invalid_messages` · `invalid_input` | Malformed request, no user text, bad embedding input |
| 401 | `missing_api_key` · `invalid_api_key` | No bearer key, or a revoked/unknown one |
| 402 | `insufficient_for_request` · `insufficient_balance` | Allowance + balance cannot cover the request |
| 402 | `spend_cap_reached` | This key's monthly cap is reached |
| 403 | `api_access_required` | The account's plan has no API access |
| 403 | `model_not_allowed` | Model not on the key's allow-list |
| 403 | `account_disabled` | Account suspended |
| 404 | `model_not_found` | Unknown or retired model — only `/v1/models` rows are callable |
| 429 | `rate_limit_exceeded` | Per-key limit (120/min); `Retry-After` says how long to wait |
| 502 | `upstream_error` | The provider failed before producing output — nothing billed |
| 502 | `upstream_interrupted` | The model failed mid-answer — the partial answer is in `error.partial_content` and was billed; `x-should-retry: false` |
| 503 | `provider_unavailable` | The model's provider (chat, embeddings or image) is not configured on this deployment — nothing billed |

---

## Calling from a browser

CORS is open on `/v1` for any origin (without credentials), so browser apps can call the API directly with `Authorization: Bearer mk_…`. **A key shipped in browser code is visible to every visitor.** For such keys: set a tight spend cap and an allowed-model list, rotate them regularly, or proxy through your own backend where the key stays private.

---

## Best practices

- Keep keys in environment variables or a secrets manager, one key per application or environment, and revoke keys you no longer use.
- Put a spend cap on every key; alert on `402 spend_cap_reached` in your logs.
- Read `usage` from every response (or the last streamed chunk) and reconcile with `GET /v1/usage`.
- Choose the model per task: the price list is live, and a smaller model is often enough.
- Send `max_tokens` when you know the answer size — it bounds the reserve and the bill.
- Handle 429 by waiting `Retry-After` seconds (exponential backoff on top is fine); treat 402 as a configuration signal, not a transient error.

---

## Coming next

- Tool-calling passthrough (`tools` / `tool_choice` are accepted today but not executed).
- Video and 3D generation through `/v1`.
- Per-key IP allow-lists.
