Luma API ушла далеко вперёд по сравнению со многими руководствами по Dream Machine, которые всё ещё распространяются в интернете. В текущей документации Luma Agents указаны uni-1 и uni-1-max для изображений, а также ray-3.2 для видео — всё это работает через асинхронный REST-процесс. В её руководстве по ценообразованию описан доступ с оплатой по факту использования, без минимальных расходов и контракта. В документации не указана постоянная бесплатная квота API.
Эту формулировку легко неверно истолковать. Небольшой прототип может стоить совсем недорого, но отсутствие минимальных расходов не означает, что каждый запрос бесплатен. У команд, которые хотят протестировать несколько видеомоделей, а не функцию, уникальную для Luma, есть другой вариант: использовать OdiRouter для сравнения моделей, действительно представленных в его актуальном каталоге. Доступность и цены следует проверять непосредственно перед внедрением.
Что разработчики получают от текущего Luma API
Luma Agents API использует один эндпоинт генерации для нескольких задач:
uni-1иuni-1-maxсоздают и редактируют изображения.ray-3.2поддерживает рабочие процессы преобразования текста в видео, изображения в видео, редактирования видео, перекадрирования и продления видео.Задачи проходят через состояния
queued,processing,completedилиfailed.Готовый результат поступает через предварительно подписанный URL-адрес. Согласно текущей схеме ответа, срок действия этого URL-адреса истекает через час, поэтому вскоре после завершения приложение должно скопировать ресурс в долговременное хранилище.
Базовый URL-адрес: https://agents.lumalabs.ai/v1. В каждом запросе используется токен Bearer в заголовке Authorization, а официальные SDK по умолчанию считывают ключ из LUMA_AGENTS_API_KEY.
В старых примерах Dream Machine используются https://api.lumalabs.ai/dream-machine/v1/generations и названия моделей, такие как ray-2. Существующим интеграциям всё ещё могут требоваться эти ссылки. Новый проект следует начинать с актуального Luma Agents quickstart и перед использованием старого примера кода подтвердить версию API.
Есть ли у Luma API бесплатный тариф?
Не считайте отсутствие минимальных расходов доказательством наличия постоянного бесплатного тарифа. Текущий pricing documentation от Luma описывает два коммерческих варианта.
При модели оплаты по мере использования счёт выставляется за каждую генерацию изображения или видео без минимальных расходов и без контракта. Provisioned Throughput предполагает обязательство по резервированию мощности для производственных нагрузок, которым необходимы предсказуемая пропускная способность и задержка.
Стоимость изображений зависит от модели и количества референсов. Стоимость видео зависит от режима работы, разрешения, динамического диапазона и продолжительности. Эти условия могут измениться. Перед утверждением бюджета или публикацией цены проверьте страницу с актуальными ценами и панель управления учетной записью.
Для управляемого прототипа:
Начните с небольшого количества запросов и одного результата для каждого тестового случая.
Используйте черновой вариант или более низкое разрешение, если этого достаточно для проверки тестируемого вопроса.
Установите в приложении лимит расходов и прекратите создание заданий, когда он будет достигнут.
Для каждого запроса запишите модель, принцип работы, разрешение, продолжительность и сумму возврата.
Отслеживайте технические сбои отдельно от завершённых результатов, не соответствующих творческому заданию.
Отправьте задачу, опрашивайте её статус, затем сохраните результат
Жизненный цикл запроса состоит из трёх частей. Создайте генерацию с помощью POST /v1/generations, опрашивайте её через GET /v1/generations/{generation_id} и скачайте файл после перехода состояния в completed.
Этот запрос соответствует текущему официальному примеру для видео. Секрет хранится в переменной окружения, а не в исходном коде.
curl -X POST https://agents.lumalabs.ai/v1/generations \
-H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ray-3.2",
"type": "video",
"prompt": "A slow tracking shot through a greenhouse at sunrise",
"aspect_ratio": "16:9",
"video": {
"resolution": "720p",
"duration": "5s"
}
}'Сохраните идентификатор генерации из ответа. Успешная отправка означает лишь, что задача была принята. Опрашивайте конечную точку статуса, пока она не достигнет конечного состояния.
curl -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
"https://agents.lumalabs.ai/v1/generations/$GENERATION_ID"Когда задача будет выполнена, прочитайте URL первого результата и скопируйте файл в хранилище, контролируемое вашим приложением. В случае сбоя сохраните failure_code, failure_reason и X-Request-Id. Этих полей достаточно для диагностики без записи в журналы ключа API или заголовка authorization.
Меры защиты для производственного воркера
Генерацию изображений и видео следует запускать в воркере с жёстким дедлайном и ограниченным циклом опроса. Для задач по видео обычно требуется более длительный дедлайн, чем для задач по изображениям.
В руководстве Luma по ограничениям скорости рекомендуется выполнять опрос каждые две—пять секунд. Отправка запросов ограничена числом запросов в минуту и количеством активных задач. Превышение любого из этих лимитов может вернуть HTTP 429. Ответ может содержать Retry-After; успешные отправки предоставляют X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.
Рабочий процесс для продакшена должен:
Учитывать
Retry-Afterперед повторной отправкой.Прекращать опрос при
completedилиfailed.Собирать
X-Request-IdиX-API-Versionвместе с очищенными метаданными задачи.Назначать новый ID запроса для каждой повторной попытки, чтобы попытки можно было различать.
Хранить API-ключи в хранилище секретов или переменной окружения и отзывать ключ, который мог быть скомпрометирован.
Скачивать готовые ресурсы до истечения срока действия их предварительно подписанных URL-адресов.
Когда имеет смысл прямой доступ к Luma
Используйте Luma напрямую, если продукту требуются ray-3.2, uni-1, uni-1-max или специфичные для Luma средства управления ключевыми кадрами, HDR, EXR, редактированием либо рекадрированием. Прямой доступ также предоставляет команде текущие SDK Luma, условия ценообразования, коды ошибок и канал поддержки поставщика.
Это также более очевидный выбор, когда подсказки и элементы управления уже были проверены на соответствие выходным данным Luma. Привязывайте эту интеграцию к актуальной документации, а не к руководству без даты публикации.
Где находится OdiRouter
OdiRouter отвечает иной потребности. Это полезно, когда команда хочет сравнить несколько моделей изображений или видео, управлять доступом из одной учетной записи или протестировать модель из текущей бесплатной категории, прежде чем выбрать платный вариант. В описании OdiRouter quickstart указан один ключ API для поддерживаемых возможностей и асинхронный протокол очереди для многомодальных заданий.
На 2026-08-07 официальный API каталога OdiRouter вернул 215 моделей, включая 81 записей видео и 20 записей в категории Free. В этом снимке не было ни одного ID модели, названия, поставщика или эндпоинта с «Luma» в названии. На основании этих данных, адрес OdiRouter не следует представлять как шлюз Luma API.
Каталог включал видеоэндпоинты, такие как kling-v3-t2v, kling-v3-i2v и minimax-t2v-01. Это альтернативы для оценки, а не полноценные замены всех функций Luma. Перед сменой поставщика проверьте их входные данные, элементы управления, формат вывода, единицу тарификации и поведение очереди.
Используйте OdiRouter model catalog как источник истины. Фильтр видео сужает каталог до актуальных вариантов для видео. Фильтр Free показывает модели, которые в настоящее время предлагаются для тестирования. Оба списка могут измениться после публикации.
Выберите путь, соответствующий требованиям
Прямой доступ к Luma лучше подходит, когда приложению нужны конкретная модель Luma, функция, доступная только в Luma, либо прямые коммерческие отношения и поддержка со стороны Luma.
OdiRouter стоит оценить, если команда хочет сравнить доступные на данный момент модели через одну учётную запись, протестировать эндпоинт из категории Free или использовать один документированный шаблон очереди для нескольких мультимодальных моделей.
Какой бы путь вы ни выбрали, перед написанием интеграции подтвердите актуальную страницу модели, цены и схему запроса. Каталоги моделей и коммерческие условия меняются быстрее, чем руководства.
Начните с одной ограниченной задачи генерации
Для разработки, специфичной для Luma, откройте current Luma Agents quickstart и руководство по ценообразованию. Для оценки нескольких моделей выберите актуально представленный эндпоинт в OdiRouter catalog и следуйте OdiRouter quickstart.
Первым полезным результатом станет одна ограниченная задача с зафиксированными моделью, входными данными, историей статусов, стоимостью, ID запроса и устойчивым местоположением результата. Эта запись даёт команде достаточно оснований для выбора следующего эндпоинта, не полагаясь на устаревшее утверждение о бесплатном тарифе.