MLMux API

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

1. 01

   Создать API-ключ

   Создайте ключ в разделе Консоль → API-ключи. Полный ключ показывается только один раз, поэтому сохраните его сразу, например, как MLMUX_API_KEY.

2. 02

   Отправьте запрос

   Вызовите эндпоинт генерации изображений или видео, передав ID модели и промпт. Списания производятся с аккаунта, которому принадлежит ключ.

3. 03

   Получите результат

   Запросы на генерацию изображений возвращают URL прямо в ответе. Запросы на генерацию видео возвращают задачу: опрашивайте её poll_url или подпишитесь на вебхук.

Аутентификация

Передавайте ключ в заголовке Authorization: Bearer при каждом запросе к https://api.mlmux.com. Ключи начинаются с sk-. API не принимает ключи в других заголовках или в строке запроса.

Чтобы проверить работоспособность ключа, запросите список доступных моделей:

curl https://api.mlmux.com/v1/models \
  -H "Authorization: Bearer $MLMUX_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "nano-banana-2", "object": "model", "owned_by": "platform" },
    { "id": "model/seedance-2.5-max", "object": "model", "owned_by": "platform" }
  ]
}

Эндпоинты

Все эндпоинты доступны по адресу https://api.mlmux.com. Тела запросов и ответов передаются в формате JSON, если не указано иное.

Режим маршрутизации

Укажите route_mode в теле запроса, чтобы выбрать уровень upstream. Запрос остается на своем уровне и никогда незаметно не переключается на другой; если уровень отключен для модели, запрос завершается с ошибкой route_mode_disabled. Если поле не указано, MLMux использует режимы маршрутизации, настроенные для API-ключа, а затем значение модели по умолчанию — official-cheap.

Биллинг

Использование оплачивается кредитами, где 1 кредит равен 1 доллару США. Видеомодели тарифицируются за выходной токен; модели изображений — за токен провайдера или за изображение в зависимости от модели. Тарифы для каждого маршрута приведены на странице с ценами.

В ответах задач указывается estimated_charge_credits при создании задачи и actual_charge_credits после её успешного завершения (оба значения в кредитах). В полезной нагрузке вебхуков передаётся actual_charge_nano_credits в виде целого числа, где 1,000,000,000 нанокредитов равны 1 кредиту.

Проверить остаток баланса можно с помощью GET /v1/account/balance.

Задачи и поллинг

Запросы на генерацию видео, а также запросы на генерацию изображений с параметром "async": true, возвращают HTTP 202 с объектом задачи. Опрашивайте poll_url задачи каждые несколько секунд, пока её статус не станет succeeded, failed, expired или canceled.

Отмена задачи

Задачи в статусе queued, submitted или running можно отменить, при этом заблокированные кредиты будут возвращены. Ответ: {"id": "task_…", "status": "canceled"}. Для задач в любом другом статусе возвращается ошибка 409 task_not_cancelable.

Безопасные повторные попытки

Асинхронные запросы на генерацию видео и изображений принимают заголовок Idempotency-Key длиной до 160 символов. Повторная отправка того же ключа с тем же телом запроса возвращает исходную задачу вместо создания новой. Отправка того же ключа с другим телом возвращает 409 idempotency_key_reused. Синхронные запросы и редактирование изображений этот заголовок не поддерживают.

Загрузка файлов

Чтобы использовать локальный файл в качестве референса, загрузите его в multipart-поле file. Принимаются изображения, видео и аудио размером до 50 МБ; они хранятся в течение 3 дней. Передавайте возвращённый url в любых полях URL запроса на генерацию.

curl https://api.mlmux.com/v1/uploads \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -F "file=@start-frame.jpg"

{
  "url": "https://.../uploads/3f8a....jpg",
  "asset_id": 1024,
  "mime_type": "image/jpeg",
  "size_bytes": 482113,
  "asset_type": "image"
}

Вебхуки

Создайте эндпоинт в Console → Webhooks и выберите события для получения. Когда запрос или задача завершается, MLMux отправляет POST-запрос с телом в формате JSON на ваш URL.

{
  "event_id": "evt_5b0d...",
  "event_type": "request.succeeded",
  "created_at": "2026-10-26T08:00:00Z",
  "data": {
    "request_id": "task_task_01a9...",
    "task_id": "task_01a9...",
    "public_model_id": "model/seedance-2.5-max",
    "api_method": "videos.generations.create",
    "image_count": 0,
    "image_resolution": "",
    "video_seconds": 8,
    "video_resolution": "720p",
    "actual_charge_nano_credits": 1790000000,
    "latency_ms": 94210
  }
}

Проверка подписей

Каждая доставка подписывается секретным ключом эндпоинта (whsec_…), который отображается один раз при его создании или ротации. Заголовок X-MLMux-Signature содержит Unix-штамп времени t и подпись v1: hex-строку HMAC-SHA256 от штампа времени, точки и необработанного тела запроса. Вычислите то же значение, сравните его и отклоняйте устаревшие штампы времени.

import crypto from "node:crypto";

// header: X-MLMux-Signature: t=1767225600,v1=5f8c...
export function verifyMLMuxSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

Возвращайте любой статус 2xx в течение 10 секунд. MLMux выполняет до 6 попыток доставки в течение приблизительно 11 часов. Используйте X-MLMux-Event-ID для игнорирования дубликатов.

Ошибки

Ошибки имеют единый формат JSON. Делайте ветвление по code, а не по message. При обращении в поддержку указывайте request_id, который также возвращается в заголовке X-Request-ID.

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "request_id": "req_9f2c..."
  }
}

Ответы со статусом 429 содержат заголовок Retry-After. Подождите указанное количество секунд перед повтором запроса, а ошибки 5xx повторяйте с экспоненциальной задержкой.