Перейти к содержанию

Разработчикам

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

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

Обновлено:


Базовый 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 и отправьте первый запрос.
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 внутри веб-приложения строится по этому эндпоинту.


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

  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(...) работает без изменений).

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.

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