Разработчикам
Руководство по API
Используйте любую модель Milly Lab из собственного кода — на любом языке, на любой платформе, с сервера или из браузера — через OpenAI-совместимый API, который выставляет счёт через ваш аккаунт Milly Lab. Здесь описаны первый запрос, настройка SDK, стриминг, живые цены, правила биллинга, ограничения на ключ, лимиты, коды ошибок и эндпоинт использования.
Базовый URL #
https://api.m-lab.app/v1
Все эндпоинты ниже указаны относительно этого адреса. Это руководство и есть справочник по публичному API: схему OpenAPI Milly Lab не публикует.
Быстрый старт #
- Создайте ключ. В веб-приложении откройте Настройки → Безопасность → API-ключи (туда же ведёт кнопка Управлять API-ключами на странице API) и нажмите Открыть API-ключи. Откроется страница API-ключей в полной консоли; там нажмите Создать ключ. Доступ к API входит в тариф Max и выше. Сырой ключ (
mk_…) показывается один раз; хранятся только последние четыре символа. - Направьте OpenAI SDK на базовый URL. Любой клиент, говорящий на протоколе OpenAI chat-completions, работает после замены base URL.
- Выберите модель из
GET /v1/modelsи отправьте первый запрос.
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
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
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 (любая среда)
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 не повторял вызов сам.
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 модели с одной ценой за единицу: столько стоит вызов при оплате с баланса.
{
"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 внутри веб-приложения строится по этому эндпоинту.
Правила биллинга #
- Сначала тариф. Если модель входит в ваш тариф, запрос сначала покрывает месячный лимит тарифа для этой модели.
- Затем баланс. Всё, что лимит не покрывает, оплачивается с пополняемого баланса: токены × указанная цена модели (
input_per_1m_usdиoutput_per_1m_usd; изображения: цена изper_quality_usdдля запрошенного качества за изображение (per_image_usd, еслиqualityне указан); эмбеддинги: указанная цена за 1 млн входных токенов), плюс цены за длинный промпт, кеш промпта и веб-поиск ниже, когда они применяются. Все цены есть в списке моделей API и на странице «Разработчикам». - В использовании видна стоимость каждого запроса.
GET /v1/usageучитывает каждый запрос по указанной цене, оплатил ли его лимит тарифа или баланс; Настройки → Платежи показывают, сколько списано с баланса. - Резерв до расхода. Запрос, который не покрывается остатком лимита плюс балансом, отклоняется с 402 до обращения к провайдеру; на время генерации платформа удерживает худший случай и затем сводит к фактическому использованию. Если провайдер модели не настроен на развёртывании, ответ — 503
provider_unavailable, тоже до любого удержания, так что ничего не списывается. Провайдер, упавший до выдачи результата, — 502 без списания; вывод, успевший прийти в потоке до сбоя, оплачивается. - Ограничения на ключ (ниже) добавляют лимит расходов и список разрешённых моделей поверх правил аккаунта.
Каждый 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(...) работает без изменений).
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, если изображения покрыл лимит тарифа).
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 в ответе.
{
"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 на ключ.