# Руководство по API

Используйте любую модель Milly Lab из собственного кода — на любом языке, на любой платформе, с сервера или из браузера — через OpenAI-совместимый API, который выставляет счёт через ваш аккаунт Milly Lab. Здесь описаны первый запрос, настройка SDK, стриминг, живые цены, правила биллинга, ограничения на ключ, лимиты, коды ошибок и эндпоинт использования.

Обновлено: 2026-10-24 · <https://m-lab.app/ru/docs/api>

---

## Базовый URL

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

Все эндпоинты ниже указаны относительно этого адреса. Это руководство и есть справочник по публичному API: схему OpenAPI Milly Lab не публикует.

---

## Быстрый старт

1. **Создайте ключ.** В веб-приложении откройте Настройки → *Безопасность* → *API-ключи* (туда же ведёт кнопка **Управлять API-ключами** на странице API) и нажмите **Открыть API-ключи**. Откроется страница API-ключей в полной консоли; там нажмите *Создать ключ*. Доступ к API входит в тариф **Max** и выше. Сырой ключ (`mk_…`) показывается один раз; хранятся только последние четыре символа.
2. **Направьте OpenAI SDK на базовый URL.** Любой клиент, говорящий на протоколе OpenAI chat-completions, работает после замены base URL.
3. **Выберите модель** из `GET /v1/models` и отправьте первый запрос.

```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": "Три факта о Душанбе."}]}'
```

Ответ — стандартный объект `chat.completion` с `choices[0].message.content` и `usage` (токены, за которые списаны средства).

---

## Настройка SDK

### 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": "Три факта о Душанбе."}],
)
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: "Три факта о Душанбе." }],
});
console.log(r.choices[0].message.content, r.usage);
```

### Обычный fetch (любая среда)

```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: "Три факта о Душанбе." }] }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
```

Поддерживаемые поля запроса: `model`, `messages` (роли `system`/`developer`, `user`, `assistant`; строка или части `text`; у моделей с `capabilities.vision` = true также части `image_url` — URL `data:` или `https:` на изображение PNG, JPEG, GIF или WebP до 5 МБ, не больше 8 за запрос), `stream`, `max_tokens` / `max_completion_tokens`, `reasoning_effort` (`low` · `medium` · `high`). Поля сэмплирования (`temperature`, `top_p`, …) принимаются для совместимости; сэмплирование выбирает маршрутизатор платформы. `tools`, `tool_choice` и сообщения tool/function принимаются, но **пока не выполняются** — см. *Что дальше*.

---

## Стриминг

Укажите `stream: true`, чтобы получать server-sent events. Каждое событие — `chat.completion.chunk`; последний чанк содержит `finish_reason` и `usage`, затем `data: [DONE]`. Пока модель думает и ещё не пишет, поток каждые несколько секунд присылает строку-комментарий (`: keepalive`), чтобы прокси и клиенты не закрыли соединение; SSE-клиенты, включая SDK OpenAI, такие строки пропускают.

Если модель сбилась посреди ответа, ответ никогда не выдаётся за полный: поток присылает событие `error` (код `upstream_interrupted`; SDK OpenAI выбрасывают на нём ошибку), а в последнем чанке `finish_reason: "error"`; вызов без потока отвечает `502 upstream_interrupted`: то, что модель успела написать, — в `error.partial_content`, списанный `usage` — там же, плюс заголовок `x-should-retry: false`, чтобы SDK не повторял вызов сам.

```python
stream = client.chat.completions.create(model="claude-sonnet-5", stream=True,
    messages=[{"role": "user", "content": "Напиши хайку о горах."}])
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)
```

Если клиент отключится посреди стрима, генерация на платформе всё равно доходит до конца, и произведённые токены оплачиваются.

---

## Модели и живые цены

`GET /v1/models` — публичный (ключ не нужен) и возвращает все доступные через API модели с одной ценой за единицу: столько стоит вызов при оплате с баланса.

```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 также содержат цены токенов кеша промпта — `cache_write_5m_per_1m_usd`, `cache_write_1h_per_1m_usd` и `cache_read_per_1m_usd`, за 1 млн токенов — и `web_search_per_request_usd`, цену одного веб-поиска. У модели со второй ценой для длинных промптов есть поле `long_context`; у Claude Haiku 5.5 это `{"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}`. Строки моделей OpenAI содержат `cache_write_30m_per_1m_usd` и `cache_read_per_1m_usd`. Строка Grok тоже содержит `web_search_per_request_usd`, пока Grok выполняет собственный веб-поиск. Как применяется каждое поле — в разделе «Правила биллинга» ниже.

У моделей изображений `pricing.unit = "per_image"` с полем `per_image_usd` — ценой одного изображения стандартного качества — и полем `per_quality_usd` — ценой одного изображения для каждого качества, которое поддерживает модель (например, `{"low": …, "standard": …, "high": …}`): ровно столько списывается с баланса за вызов с этим качеством. Модель эмбеддингов указана с `modality: "embedding"`. При вызове `/v1/models` **с ключом** каждая строка дополнительно содержит `allowed_for_key` — может ли этот ключ вызывать модель — и `included_in_plan` — выделяет ли тариф аккаунта эту модель (сначала лимит) или каждый вызов оплачивается с баланса; поле верхнего уровня `plan` называет тариф. При балансе $0 невключённая модель отвечает 402 с первого токена.

Вызывать можно только перечисленные модели. Снятый ключ без преемника (`gpt-5.4-mini`) отвечает **404** `model_not_found`; устаревший псевдоним, указывающий на текущую модель (`claude-sonnet` → `claude-sonnet-5`, `claude-haiku-4-5` → `claude-haiku-5-5`, `gpt-4o` → `gpt-5.4-nano`), по-прежнему работает и оплачивается по опубликованной ставке модели, которая на него отвечает.

Живая таблица на странице **API** внутри веб-приложения строится по этому эндпоинту.

---

## Правила биллинга

1. **Сначала тариф.** Если модель входит в ваш тариф, запрос сначала покрывает месячный лимит тарифа для этой модели.
2. **Затем баланс.** Всё, что лимит не покрывает, оплачивается с пополняемого баланса: токены × **указанная цена** модели (`input_per_1m_usd` и `output_per_1m_usd`; изображения: цена из `per_quality_usd` для запрошенного качества за изображение (`per_image_usd`, если `quality` не указан); эмбеддинги: указанная цена за 1 млн входных токенов), плюс цены за длинный промпт, кеш промпта и веб-поиск ниже, когда они применяются. Все цены есть в списке моделей API и на странице «Разработчикам».
3. **В использовании видна стоимость каждого запроса.** `GET /v1/usage` учитывает каждый запрос по указанной цене, оплатил ли его лимит тарифа или баланс; Настройки → *Платежи* показывают, сколько списано с баланса.
4. **Резерв до расхода.** Запрос, который не покрывается остатком лимита плюс балансом, отклоняется с **402** *до* обращения к провайдеру; на время генерации платформа удерживает худший случай и затем сводит к фактическому использованию. Если провайдер модели не настроен на развёртывании, ответ — **503** `provider_unavailable`, тоже до любого удержания, так что ничего не списывается. Провайдер, упавший до выдачи результата, — **502** без списания; вывод, успевший прийти в потоке до сбоя, оплачивается.
5. **Ограничения на ключ** (ниже) добавляют лимит расходов и список разрешённых моделей поверх правил аккаунта.

Каждый API-запрос записывает строку использования с меткой ключа; эти строки питают Настройки → *Биллинг*, показатель *потрачено в этом месяце* у ключа и `GET /v1/usage`.

### Длинные промпты, кеш промпта и веб-поиск

У каждого из них своя указанная цена в строке модели в `GET /v1/models`, а `usage` ответа содержит количества, к которым она применяется:

- **Длинные промпты.** Запрос, промпт которого — `usage.prompt_tokens`, все входные токены, включая кешированные, — длиннее `pricing.long_context.threshold_prompt_tokens`, целиком оплачивается по ценам `long_context`. Claude Haiku 5.5: до 100 000 токенов промпта — $2.20 за 1 млн входных и $3.00 за 1 млн выходных токенов; сверх этого — $3.00 и $7.00. Вторая цена есть и у моделей OpenAI (свыше 272 000 токенов промпта) и у Grok (от 200 000, в списке — свыше 199 999); у каждой модели она указана в её строке. Каждый запрос цикла инструментов оплачивается по своему промпту.
- **Кеш промпта (Claude).** Claude хранит повторяющиеся начала промпта в кеше. Из токенов промпта записанные в кеш (`usage.prompt_tokens_details.cache_write_tokens`, из них на час — `cache_write_1h_tokens`) оплачиваются по `cache_write_5m_per_1m_usd` (запись на час — по `cache_write_1h_per_1m_usd`), прочитанные из кеша (`usage.prompt_tokens_details.cached_tokens`) — по `cache_read_per_1m_usd`, остальные — по `input_per_1m_usd`. Для длинного промпта действуют три цены кеша из `long_context`.
- **Кеш промпта (OpenAI).** Модели OpenAI кешируют повторяющиеся начала промпта автоматически. Из токенов промпта записанные в кеш (`usage.prompt_tokens_details.cache_write_tokens`, хранятся 30 минут) оплачиваются по `cache_write_30m_per_1m_usd`, прочитанные из кеша (`usage.prompt_tokens_details.cached_tokens`) — по `cache_read_per_1m_usd`, остальные — по `input_per_1m_usd`. Для длинного промпта действуют две цены кеша из `long_context`.
- **Веб-поиск (Claude, Grok).** Каждый веб-поиск, который модель выполняет для ответа (`usage.web_search_requests`), добавляет `web_search_per_request_usd` своей строки (Claude $0.02, Grok $0.01).
- **Округление.** Сумма каждого запроса округляется до $0.000001, поэтому итог, посчитанный вами по указанным ценам, может отличаться от неё на несколько миллионных долей доллара.

---

## Ограничения на ключ

Задаются при создании или позже на странице API-ключей в полной консоли (Настройки → *Безопасность* → *API-ключи* → *Открыть API-ключи*) или запросом `PATCH /api/keys/{id}` из веб-сессии:

| Ограничение | Поведение |
|---|---|
| **Месячный лимит расходов** (USD, целые центы — `0.05`, а не `0.001`; более точное значение отклоняется с 422) | Когда расходы ключа с начала месяца (каждый запрос по указанной цене, оплатил ли его лимит тарифа или баланс) достигают лимита, дальнейшие вызовы возвращают **402** `spend_cap_reached`. Запрос, пересекающий черту, ещё выполняется (его стоимость неизвестна до завершения), поэтому превышение — не больше одного запроса. Сброс 1-го числа каждого месяца (UTC). |
| **Разрешённые модели** | Список ключей каталога. Любая другая модель возвращает **403** `model_not_allowed`. Пусто = все API-модели. Устаревшие псевдонимы приводятся к текущему ключу. |

Используйте оба ограничения для любого ключа, покидающего вашу инфраструктуру.

---

## Эмбеддинги

`POST /v1/embeddings` — OpenAI-совместимый. Модель `text-embedding-3-small` (1536 измерений). `input` — строка или список до 256 строк (по 12 000 символов). Оплата по входным токенам; эмбеддинги не входят ни в один тарифный лимит, поэтому всегда оплачиваются с баланса. `encoding_format` — `float` (по умолчанию) или `base64` (float32 little-endian — именно его официальные SDK запрашивают по умолчанию, поэтому `client.embeddings.create(...)` работает без изменений).

```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)
```

---

## Изображения

`POST /v1/images/generations` — OpenAI-совместимые запрос и ответ. `model` — ключ модели изображений из `/v1/models` (`gpt-image-2`, `gemini-nano-banana`, `fal-ai/flux-pro`, `fal-ai/stable-diffusion-xl`), `n` 1–4, `size` `1024x1024` · `1536x1024` · `1024x1536` (приводится к ближайшему соотношению сторон модели), `quality` `low` · `standard` · `high` (`medium`/`hd` принимаются). Вызов синхронный (до 180 с) и возвращает размещённые `url`; `usage.billed_usd` — сумма, списанная с баланса (0, если изображения покрыл лимит тарифа).

```python
img = client.images.generate(model="gpt-image-2", prompt="Акварельная карта Памира", size="1024x1024")
print(img.data[0].url)
```

Изображения, созданные через API, не добавляются в историю Light Studio.

---

## Эндпоинт использования

`GET /v1/usage?from=YYYY-MM-DD&to=YYYY-MM-DD[&key=<id>]` возвращает запросы, токены и **расходы по указанным ценам** (каждый запрос по указанной цене, оплатил ли его лимит тарифа или баланс). С неограниченным ключом (без списка моделей и без лимита расходов) — по **всем ключам аккаунта**: один отчётный ключ может наблюдать за всеми (`scope: "account"`). Ограниченный ключ — со списком разрешённых моделей или лимитом расходов, как советуем для ключей, которые могут увидеть посторонние (например, в коде для браузера), — видит **только свои расходы** (`scope: "key"`), а `key=` с другим ключом отвечает 404. Диапазон по умолчанию — с начала месяца; максимум 92 дня. Чат веб-приложения никогда не включается. `tokens_in` считает все входные токены, включая кешированные, — так же, как `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 }]
}
```

---

## Лимиты

| Лимит | Значение |
|---|---|
| Запросов на ключ | 120 в минуту → **429** `rate_limit_exceeded` с `Retry-After` (секунды) |
| Активных ключей на аккаунт | 5 |
| Сообщений в запросе | 200 |
| Символов в запросе | 400 000 |
| Входов эмбеддинга за вызов | 256 × 12 000 символов |
| Изображений за вызов | 4 |

Каждый ответ `/v1` несёт `x-request-id` (`req_…`; укажите его при обращении в поддержку — это собственный номер вызова: он записан в журнал вместе с вызовом и сохранён с его расходом, а `id` ответа чата содержит те же символы) и, после аутентификации ключа, `x-ratelimit-limit`, `x-ratelimit-remaining` и `x-ratelimit-window` (секунды). 429 добавляет `Retry-After` — подождите столько секунд и повторите. 402 не повторяйте, ничего не изменив (пополните баланс, поднимите лимит, выберите более дешёвую модель).

---

## Коды ошибок

Каждая ошибка в формате OpenAI: `{"error": {"message": "…", "type": "…", "code": "…"}}` — ветвитесь по `code`.

| HTTP | `code` | Значение |
|---|---|---|
| 400 | `invalid_body` · `invalid_messages` · `invalid_input` | Некорректный запрос, нет текста пользователя, плохой вход эмбеддинга |
| 401 | `missing_api_key` · `invalid_api_key` | Нет bearer-ключа, либо он отозван/неизвестен |
| 402 | `insufficient_for_request` · `insufficient_balance` | Лимит + баланс не покрывают запрос |
| 402 | `spend_cap_reached` | Достигнут месячный лимит этого ключа |
| 403 | `api_access_required` | В тарифе аккаунта нет доступа к API |
| 403 | `model_not_allowed` | Модель не в списке разрешённых для ключа |
| 403 | `account_disabled` | Аккаунт заблокирован |
| 404 | `model_not_found` | Неизвестная или снятая модель — вызывать можно только строки `/v1/models` |
| 429 | `rate_limit_exceeded` | Лимит на ключ (120/мин); `Retry-After` говорит, сколько ждать |
| 502 | `upstream_error` | Провайдер упал, не выдав результата — ничего не списано |
| 502 | `upstream_interrupted` | Модель сбилась посреди ответа — начало ответа в `error.partial_content`, оно списано; `x-should-retry: false` |
| 503 | `provider_unavailable` | Провайдер модели (чат, эмбеддинги или изображения) не настроен на этом развёртывании — ничего не списано |

---

## Вызов из браузера

CORS открыт на `/v1` для любого источника (без credentials), так что браузерные приложения могут обращаться к API напрямую с `Authorization: Bearer mk_…`. **Ключ, отправленный в браузерном коде, виден каждому посетителю.** Для таких ключей: задайте жёсткий лимит расходов и список разрешённых моделей, регулярно меняйте их либо проксируйте через собственный бэкенд, где ключ остаётся приватным.

---

## Рекомендации

- Храните ключи в переменных окружения или менеджере секретов, по одному ключу на приложение или среду; отзывайте неиспользуемые.
- Ставьте лимит расходов на каждый ключ; настройте оповещение на `402 spend_cap_reached` в логах.
- Читайте `usage` из каждого ответа (или последнего чанка стрима) и сверяйте с `GET /v1/usage`.
- Подбирайте модель под задачу: цены живые, и меньшей модели часто достаточно.
- Передавайте `max_tokens`, когда знаете размер ответа — это ограничивает резерв и счёт.
- На 429 подождите `Retry-After` секунд (экспоненциальная пауза сверху не помешает); 402 — сигнал конфигурации, а не временная ошибка.

---

## Что дальше

- Проброс вызова инструментов (`tools` / `tool_choice` принимаются, но пока не выполняются).
- Генерация видео и 3D через `/v1`.
- Списки разрешённых IP на ключ.
