Luma API — это сервис для генерации изображений и видео. Это не универсальная платформа для обучения моделей машинного обучения, выполнения рабочих нагрузок NLP или работы с системами предиктивной аналитики build. Это руководство основано на актуальной первичной документации: что делает API, как работает поток запросов, что «бесплатно» может означать или не означать, а также что следует сравнить перед внедрением API для видео в производство.
Краткий ответ
Luma от Dream Machine API поддерживает рабочие процессы генерации изображений, преобразования текста в видео и преобразования изображения в видео. В руководстве по видео указан Ray 2 Flash с идентификатором модели ray-flash-2. В нём указан Ray 2 с идентификатором модели ray-2. Вы создаёте генерацию, получаете идентификатор и проверяете эту генерацию, пока результат не будет готов.
На официальных страницах, изученных для этого руководства, не указано постоянное ежемесячное количество бесплатных вызовов API. Они направляют пользователей к API-ключам, данным об использовании, биллингу и тарифу Build с опубликованными лимитами запросов и расходов. Если в аккаунте отображаются бесплатные кредиты, считайте их текущим предложением для этого аккаунта. Прежде чем учитывать их в оценке расходов, подтвердите их размер и срок действия в интерфейсе биллинга Luma.
Что подтверждает актуальная документация Luma
В Luma API overview описаны две категории медиа. Генерация видео поддерживает преобразование текста в видео и изображения в видео. Генерация изображений поддерживает текстовые запросы, референсы персонажей, референсы изображений, референсы стиля и модификацию изображений.
В official video generation guide описаны аутентификация Bearer, идентификаторы моделей Ray и конечная точка генерации. Его примеры охватывают промпты, ключевые кадры, соотношение сторон, циклы, концепции, разрешение, длительность и расширение видео. Эти параметры не обязательно применимы к каждой модели или типу запроса. Проверьте актуальную схему для модели, которую планируете вызывать.
Руководство также направляет читателей к документации по API Platform и более новой Agents API, где опубликованы последние материалы. Это уведомление легко упустить из виду, однако оно важно. Модели, примеры и правила для аккаунтов могут меняться быстрее, чем обновляются сторонние учебные материалы.
Что на самом деле нужно проверить в отношении «бесплатного»
Бесплатные кредиты, цены, ограничения скорости и ежемесячные лимиты использования — это разные вещи.
Бесплатный кредит или пробный период имеют денежную стоимость и могут истечь.
Цена — это плата за выработку электроэнергии или другую оплачиваемую единицу продукции.
Ограничение скорости обработки запросов определяет, с какой скоростью вы можете создавать или обрабатывать запросы.
Для определенного уровня учетной записи установлен ежемесячный лимит использования, определяющий объем расходов или потребления.
official rate-limit page публикует лимиты для тарифа Build. В нём указано 10 одновременных генераций видео. Это позволяет обрабатывать запросы на генерацию 20 в минуту. Также указан ежемесячный лимит использования в размере 5,000 долларов США. Эти цифры описывают пропускную способность и лимит на количество учетных записей. Они не указывают, что API является бесплатным.
Информацию о кредитах и ценах смотрите на странице оплаты в режиме реального времени. Затем оцените стоимость, исходя из разрешения, продолжительности, частоты повторных попыток и ожидаемого объема генерации. Лимит запросов не может ответить на этот вопрос за вас.
Как работает асинхронный поток запросов
Генерация видео занимает больше времени, чем обычный ответ JSON, поэтому API использует поток заданий:
Создайте API-ключ и храните его в менеджере секретов или переменной окружения.
Отправьте запрос на генерацию с действительной моделью и полезной нагрузкой.
Сохраните возвращённый идентификатор генерации рядом с идентификатором своего пользователя или рабочего процесса.
Опрашивайте конечную точку генерации или используйте документированный обратный вызов, если он доступен.
Явно обрабатывайте состояния: в очереди, обработка, завершено и ошибка.
Скачайте или скопируйте готовый ресурс до окончания любого периода хранения, установленного поставщиком.
Записывайте модель, параметры, метаданные о стоимости, задержку и причину сбоя.
Этот минимальный запрос преобразования текста в видео соответствует текущему руководству Luma:
curl --request POST \
--url https://api.lumalabs.ai/dream-machine/v1/generations \
--header "Authorization: Bearer ${LUMA_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"prompt": "A paper boat crossing a rain puddle at dusk",
"model": "ray-2",
"resolution": "720p",
"duration": "5s"
}'Не допускайте попадания настоящего ключа в систему контроля версий и журналы. Первый ответ — это квитанция о задании, а не готовое видео. Вашему приложению необходимо сохранять идентификатор и возобновлять рабочий процесс после перезапуска.
Проверки перед запуском в продакшен
Контракт входных и выходных данных
Отдельно подтвердите поддержку преобразования текста в видео и изображения в видео. Если поставщику требуется публичный URL изображения, определите, кто отвечает за загрузку, как долго ресурс остаётся доступным и не раскрывает ли URL конфиденциальную информацию. Проверьте разрешение, длительность, соотношения сторон, работу со звуком и формат файла для конкретной модели.
Управление пропускной способностью и сбоями
Ограничения скорости не показывают общую задержку. Измеряйте время ожидания в очереди, время обработки, поведение при тайм-ауте, доставку обратных вызовов и безопасность повторных попыток. Используйте стратегию идемпотентности или внешних задач, если API её предоставляет. Повторная попытка из-за сетевой ошибки не должна создавать два тарифицируемых видео.
Контроль расходов
Установите бюджеты для каждого пользователя или рабочего пространства. Ведите журнал запрошенной модели, длительности, разрешения и числа повторных попыток. Отклоняйте неподдерживаемые комбинации до их отправки поставщику. Пятисекундный предпросмотр и более длинный результат в высоком разрешении не должны рассчитываться исходя из одинаковой стоимости.
Безопасность и происхождение
Зафиксируйте правила для промптов, требования к правам на медиаматериалы, политику водяных знаков и этапы проверки результатов. Храните достаточно метаданных, чтобы определить поставщика и модель, использованные для создания ресурса. Не включайте в аналитические события ключи API, закрытые медиафайлы и подписанные URL-адреса.
Когда OdiRouter имеет значение
Прямая интеграция с Luma целесообразна, когда приложению требуется конкретная модель или функция Luma. Многомодельная платформа полезна, когда команда хочет сравнить поставщиков, управлять несколькими моделями медиаконтента через одну учетную запись или выбирать разные модели для предварительного просмотра, конечного качества, продолжительности или стоимости.
OdiRouter — это название товара и целевой страницы для конверсии, но границы должны быть указаны явно. В снимке доказательств для этого руководства публичный OdiRouter model sitemap не содержал сведений об этом поставщике или конечной точке Ray. Не рассматривайте OdiRouter как прямую замену прокси Luma, если только его текущий каталог впоследствии не укажет иное.
Используйте OdiRouter model catalog для оценки поддерживаемых видеопараметров. Проверьте pricing page, прежде чем оценивать стоимость продакшена. Откройте documentation для начала работы. Один из текущих примеров — Kling V3 text-to-video endpoint.
Проверенный запрос видео OdiRouter
Текущая документация Kling V3 поддерживает текстовый промпт, необязательный негативный промпт, управление звуком, режимы генерации и соотношения сторон. Длительность составляет от 3 до 15 секунд. Режим std обеспечивает вывод в 720P. Режим pro обеспечивает вывод в 1080P. Режим 4k обеспечивает вывод в 4K. Ответ включает request_id и queue_position. Он предоставляет response_url и status_url для получения результатов и опроса статуса. Он также предоставляет cancel_url.
curl --request POST \
--url https://api.odirouter.ai/model/v1/queue/kling-v3-t2v \
--header "Authorization: Bearer ${ODIROUTER_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"prompt": "A paper boat crossing a rain puddle at dusk",
"negative_prompt": "blurred subject, broken motion",
"sound": "off",
"cfg_scale": 0.5,
"mode": "std",
"aspect_ratio": "16:9",
"duration": "5"
}'Эти URL-адреса ответа делают жизненный цикл задачи видимым. Сохраняйте идентификатор запроса, опрашивайте статус через URL-адрес статуса, получайте результат через URL-адрес ответа и предлагайте отмену только тогда, когда это допускает состояние задачи.
Используйте адаптер, если можете сменить поставщика
Для приложения, которое может вызывать более одного API для работы с видео, определите внутренний тип запроса. Он может включать промпт, референсные медиафайлы, соотношение сторон, длительность, уровень разрешения, настройку аудио, целевой адрес обратного вызова и идентификатор задачи клиента. Адаптер поставщика может преобразовать эти поля в схему запроса поставщика.
Сохраняйте доступность параметров, специфичных для поставщика, вместо того чтобы принудительно сводить каждую модель к минимальному общему набору функций. Нормализуйте состояния задач и метаданные вывода, но сохраняйте исходный ответ поставщика для отладки и проверки выставления счетов.
Это не делает две модели эквивалентными. Это даёт вашему приложению единое место для контроля бюджетов, повторных попыток, журналирования и правил безопасности, сохраняя при этом существенные различия.
Выберите следующий шаг исходя из требования
Используйте актуальную документацию Luma, когда в требовании упоминается Ray или другая возможность, специфичная для Luma. Прежде чем полагаться на заявление о «бесплатности», проверьте тарификацию.
Используйте OdiRouter, когда требуется сравнивать или использовать поддерживаемые видеомодели через одну платформу. Изучите каталог моделей, подтвердите актуальную цену и схему запроса и начните с короткой недорогой генерации, прежде чем увеличивать длительность или разрешение.