Единый API видеогенерации: Kling, Wan, Seedance и другие модели через Celestria Gate

Что получится после этой инструкции

У вас будет понятная последовательность действий для приложения, бота или сайта. Пользователь описывает сцену либо прикладывает исходные материалы. Ваш сервер проверяет параметры модели, показывает ориентировочную цену и создаёт одно задание. Когда работа завершится, сервер получает ссылку на видео, выбранного провайдера и окончательную сумму в рублях.

Единый доступ означает один ключ, общий контракт /v1/media и учёт расходов для доступных вашему аккаунту моделей. Он не делает видеомодели одинаковыми: одна принимает фотографию, другая редактирует исходный ролик, третья создаёт речь и шумы. Клиент выбирает модель и операцию, получает её схему и отправляет общий JSON; подходящий провайдер определяется на стороне Gate по совместимости и подтверждённым условиям.

Сначала выберите задачу, затем модель

Представьте три заказа. Для первого нужен новый вид осеннего леса: достаточно текста. Во втором уже есть фотография товара: нужно добавить плавное движение. В третьем есть видео с человеком и фотография другого персонажа: требуется сохранить прогулку и заменить внешность. Фраза «сгенерировать видео» описывает все три заказа слишком широко. Именно операция объясняет API, какой результат вы ожидаете.

Название семейства помогает начать поиск, но для запроса нужен полный ID из текущего каталога и операция из его схемы. Нельзя превращать Pro в Standard или выбирать Fast только из-за похожего имени: отличаются цена, ограничения и иногда качество. Страница модели и её схема важнее общего рекламного названия.

Как работают один ключ и несколько провайдеров

Ваше приложение обращается к https://api.celestriagate.com и передаёт ключ Celestria Gate в заголовке Authorization: Bearer. Для интеграции через Gate клиенту не нужен отдельный ключ fal или OpenRouter. Их подключение обслуживается на стороне Gate. Ключ храните на своём сервере: браузер отправляет пользовательское задание вашему серверу, а уже он обращается к API.

В каталоге подтверждённая модель показывается одной карточкой, а её режимы остаются отдельными операциями. Это позволяет автоматически выбирать совместимый маршрут для конкретного запроса. Модели, представленные только у одного подключённого поставщика, тоже используют общий API: наличие второго предложения не является условием доступа. Каталог включает записи, требующие проверки цены, схемы или лицензии, поэтому карточка ещё не означает готовность любого коммерческого запуска.

Начните с кабинета: создайте ключ в разделе «Ключи», проверьте баланс и доступные ограничения. Затем найдите модель и прочитайте её текущую схему. Если модель помечена недоступной, смотрите available и unavailable_reason. Попытка подобрать случайный JSON не исправит неподтверждённый тариф или лицензию.

Как выбирается выгодный провайдер

Сравнивать нужно один и тот же заказ: ту же версию модели, операцию, длительность, формат кадра, звук и остальные заданные настройки. Пятисекундный немой ролик и десятисекундный ролик с речью имеют разную стоимость. Тариф одной только «секунды видео» без этих условий не даёт честного сравнения.

Gate проверяет, какие маршруты способны выполнить переданный запрос без потери настроек. Если несколько совместимых маршрутов имеют подтверждённые сопоставимые цены, выбирается самый выгодный из них по расчёту стоимости для клиента. Неподдерживаемый параметр не должен исчезать из запроса ради более дешёвого предложения. Когда цена части вариантов не подтверждена, ответ сообщает, что сравнение неполное.

Автоматический выбор касается именно совместимых маршрутов выбранной модели. Он не заменяет Kling на Wan и не обещает самую низкую цену среди всех сервисов интернета. Время ожидания и художественное качество разных семейств тоже требуют отдельных тестов.

Поле provider возвращает fal-native для fal либо model-network для маршрута OpenRouter. Поле compared показывает число вариантов с рассчитанной ценой; оно не является количеством всех моделей в каталоге. Решение отдельной оценки не фиксирует маршрут будущего задания: актуальный выбор сохраняется при создании задания.

Шаг 1. Получите схему выбранной операции

Для учебного примера возьмём Kling 3 Pro и создание нового ролика по тексту. Канонический ID — kwaivgi/kling-v3.0-pro, операция — text-to-video. Пример с длительностью 5 секунд, форматом 16:9 и выключенным звуком проходил проверку схемы и оценки Gate без запуска платной генерации. Это подтверждение контракта запроса, а не обещание определённой картинки.

В примерах CELESTRIA_API_KEY — переменная окружения с вашим ключом. Команда ниже только получает описание полей; она не создаёт видео. В ответе смотрите input_schema: названия, обязательные поля, допустимые значения и настройки parameters. Для другой модели сначала получите её собственную схему.

curl --fail-with-body --get \
  "https://api.celestriagate.com/v1/media/models/schema" \
  -H "Authorization: Bearer $CELESTRIA_API_KEY" \
  --data-urlencode "model=kwaivgi/kling-v3.0-pro" \
  --data-urlencode "operation=text-to-video"

Шаг 2. Сохраните точный JSON задания

Создайте файл request.json в обычном текстовом редакторе и вставьте содержимое ниже. model выбирает модель, input содержит задание. operation определяет режим. prompt описывает кадр и движение. duration здесь — число 5, а generate_audio — логическое false без кавычек. Так мы явно заказываем немое видео.

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

{
  "model": "kwaivgi/kling-v3.0-pro",
  "input": {
    "operation": "text-to-video",
    "prompt": "A red fox walks slowly through an autumn forest. One continuous shot, a fixed camera, soft morning light. No text or logos.",
    "duration": 5,
    "aspect_ratio": "16:9",
    "generate_audio": false
  }
}

1. Начало кадра

   Осенний лес и одна лиса. Общая композиция должна читаться с первой секунды.

2. Действие

   Лиса медленно делает несколько шагов; в кадре остаётся то же окружение.

3. Завершение

   Камера не меняет положение, монтажного скачка и надписей не запрашиваем.

Шаг 3. Узнайте оценку до платного запуска

Отправьте request.json в /v1/media/estimate. Этот вызов проверяет возможность маршрута и возвращает предварительную оценку, не создавая платную генерацию. Если ответ содержит ошибку, сначала исправьте её. Не продолжайте запуск только потому, что похожая модель на другой странице принимает такой параметр.

В estimate.upstream_cost_usd находится предварительный расход у провайдера в долларах, а в estimate.cost_rub — оценка для клиента Gate в рублях. Значение null означает, что число не подтверждено; оно не означает бесплатную генерацию. Цена оценки может отличаться от окончательного списания после выполнения.

curl --fail-with-body \
  "https://api.celestriagate.com/v1/media/estimate" \
  -H "Authorization: Bearer $CELESTRIA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Шаг 4. Создайте одно задание и сохраните его ID

Следующая команда уже запускает потенциально платную работу. Для каждого нового самостоятельного задания придумайте собственный Idempotency-Key. Ниже показано учебное имя: в рабочем приложении подойдёт сохранённый UUID вашего заказа. Отправляйте в /generations тот же JSON, который оценивали, и сохраняйте возвращённый id.

Если связь оборвалась, сервер мог успеть принять запрос. Повторите то же тело с тем же ключом: в пределах одной организации Gate вернёт то же задание и сохранённый маршрут. Новый ключ означает новое потенциально платное задание. Если изменить тело и оставить прежний ключ, API вернёт 409, чтобы не перепутать два разных заказа.

curl --fail-with-body \
  "https://api.celestriagate.com/v1/media/generations" \
  -H "Authorization: Bearer $CELESTRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-fox-video-20261020-001" \
  --data-binary @request.json

Успешный ответ создания имеет HTTP 202 и object: media_generation. Это подтверждение постановки задания, а не готового ролика. Заголовок Location содержит путь для проверки; идентификатор сохраните вместе с вашим заказом.

Шаг 5. Дождитесь результата и проверьте списание

Получайте задание запросом GET по его ID, например раз в 5 секунд. Замените учебный идентификатор в команде настоящим id из ответа создания. Такой опрос не создаёт новых генераций. В приложении задайте конечное время ожидания: если оно истекло, сохраните ID и продолжайте позже, вместо новой платной отправки.

При completed начните с массива files, но не считайте его content_type гарантированно нормализованным: поле бывает null или application/octet-stream. Видео ищите по сочетанию MIME, расширения URL или file_name и структуры result, например result.video.url либо result.video_url. При неизвестном формате сверяйтесь с output_schema модели, а не угадывайте тип. Используйте только проверенные HTTPS-ссылки; некоторые из них ограничены по времени. Свежий GET завершённого задания может вернуть актуальную ссылку. Сам файл сохраните в своё разрешённое хранилище, если он нужен надолго.

curl --fail-with-body \
  "https://api.celestriagate.com/v1/media/generations/MEDIA_JOB_ID" \
  -H "Authorization: Bearer $CELESTRIA_API_KEY"

Итог находится в billing.cost_rub. billing.upstream_cost_usd показывает подтверждённый расход провайдера, estimated_cost_rub — предварительную оценку, reserved_rub — текущий резерв. Резерв временно уменьшает доступный баланс и не является отдельной второй покупкой. При ошибке проверяйте итоговый billing и учёт запроса; общий лозунг «любая ошибка бесплатна» некорректен.

Пример реального списания: что именно проверяли

20 октября 2026 года в обычном чате Gate провели отдельную платную проверку Kling O1: передали пятисекундное видео прогулки и фотографию женщины в жёлтом платье. Маршрут выбрал fal. Подтверждённый расход провайдера составил $0,84, окончательное списание Gate — 93,79 ₽. В результате изменился персонаж, а парк и движение сохранились; сходство лица оценить нельзя, потому что человек идёт спиной.

Это факт одного задания редактирования Kling O1 с конкретными исходниками. Он не является ценой учебного запроса Kling 3 Pro выше и не задаёт постоянный валютный курс. Для своего заказа заново получите оценку и затем сверьте окончательное списание. Для сравнения моделей берите одинаковые исходники и учитывайте количество попыток до приемлемого результата.

Если у модели есть только один совместимый провайдер

Одна точка доступа не требует, чтобы каждая модель была представлена сразу у двух поставщиков. Например, pixverse/swap, mmaudio/mmaudio-v2 и alibaba/wan-2.2-a14b-turbo имеют собственные возможности и канонические ID Gate. Вы используете те же /v1/media/models/schema, /estimate и /generations. Клиенту не нужно выбирать другой API или передавать секрет поставщика, когда совместимое предложение только одно.

В каждом input обязательно укажите operation. Общие поля — prompt, image_urls, video_url, duration, resolution, aspect_ratio и звуковые настройки, когда они предусмотрены схемой. duration передаётся числом; специфические параметры выбранной модели находятся в input.parameters. Не копируйте неизвестные настройки в новый заказ: неподдерживаемое поле должно вызвать понятную проверку, а не исчезнуть при отправке.

Причина only_compatible_route сообщает, что под конкретный запрос подошёл один маршрут. lowest_comparable_price относится к выбору меньшей подтверждённой цены из нескольких совместимых предложений. price_comparison_incomplete означает неполную проверку цен и не даёт оснований обещать абсолютный минимум. Для всех этих случаев сохраняется один контракт создания, ожидания и получения результата.

Как встроить это в существующий продукт

В обычном чате оставьте знакомую пользователю последовательность: модель, исходники, описание и отправка. Параметры показывайте из схемы выбранного режима. Под сообщением полезна кнопка «Скопировать запрос»: клиент сможет повторить точный JSON на своём сервере. Скопированный пример должен содержать модель, параметры и URL материалов, но не секретный ключ.

В истории заказа сохраняйте ваш внутренний номер, Idempotency-Key, ID задания Gate, финального провайдера и billing. Так вопрос клиента «почему списалась эта сумма?» решается по конкретному запросу. Начните с одного ролика и проверки файла. Затем расширяйте список моделей через каталог, сохраняя те же правила проверки схемы, ожидания и учёта стоимости.

Частые вопросы

Можно ли подключить все видеомодели одним ключом?

Один ключ Celestria Gate используется с общим контрактом /v1/media для доступных аккаунту моделей. Клиент выбирает канонический ID и операцию, а Gate определяет совместимый маршрут. Наличие карточки не отменяет проверку схемы, тарифа, лицензии и доступности.

Gate всегда выбирает самого дешёвого провайдера?

Выбирается меньшая подтверждённая цена среди совместимых маршрутов одной модели при сопоставимых параметрах. Если подошёл один маршрут или часть цен не подтверждена, ответ сообщает соответствующую причину. Разные семейства моделей автоматически друг на друга не подменяются.

Нужен ли клиенту собственный ключ fal?

При обращении через Gate клиент использует ключ Celestria Gate. Ключи подключённых провайдеров не нужно добавлять в его приложение. Ключ Gate храните на сервере и не включайте в публичный браузерный код.

Зачем ждать awaiting_billing, если видео уже сгенерировано?

На этом этапе подтверждается итоговый расход провайдера. До completed не считайте резерв окончательным списанием и не сообщайте клиенту вымышленную финальную сумму.

Как избежать двойной оплаты после обрыва связи?

Сохраните Idempotency-Key до отправки. Повторяйте исходное тело с тем же ключом либо получайте уже известное задание по ID. Изменённый запрос требует нового самостоятельного заказа; новый ключ может создать ещё одну платную генерацию.

Источники

• Celestria Gate: документация API
• Текущий общий каталог Gate
• Kling 3 Pro: официальная схема fal
• Kling 3 Pro: карточка OpenRouter
• fal: получение подтверждённых расходов Billing Events
• fal: тарифы моделей Pricing API