API видеогенерации: как получить каталог и выбрать подходящую модель

Опишите задачу до поиска по названиям

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

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

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

Читайте карточку модели и её доступные операции

Общий каталог GET /api/v1/catalog/models содержит карточки с каноническим id, capabilities и описанием native_generation, когда оно предусмотрено. Одна подтверждённая модель может объединять несколько операций. Это уменьшает дубли названий, но не превращает разные режимы в один: создание по тексту и редактирование исходного ролика остаются самостоятельными задачами.

Для витрины общего API отберите карточки с native_generation.schema_path = /v1/media/models/schema и используйте их data[].id как значение model будущего запроса. Поддерживаемые входы и выходы смотрите в capabilities, сведения о вариантах и готовности — в native_generation и его variants. Это метаданные карточки, а не инструкция выбрать провайдера. Схему выбранной операции получайте через общий /v1/media/models/schema с двумя явными параметрами model и operation.

Метаданные можно кэшировать для поиска, но не считать когда-то сохранённую готовность вечной. Тариф, доступность и схема меняются; окончательная проверка относится к конкретному запросу. Если у модели одно совместимое предложение, она всё равно работает через общий API. Добавлять клиенту отдельный переключатель поставщиков для этого не требуется.

Получите карточки без платной генерации

Команда ниже читает публичный каталог Gate и сохраняет JSON в catalog.json. jq отбирает карточки с общим schema_path /v1/media/models/schema и заявленным видеовыходом, затем извлекает их канонические ID вместе с метаданными готовности. Это только чтение: оно не создаёт платную генерацию. Команды рассчитаны на bash и установленный jq; для публичных карточек секрет не нужен.

Отбор по capabilities.output_modalities удобен для первого поиска, но не доказывает поддержку редактирования. Следом посмотрите native_generation.variants[].operation и получите схему нужной операции. В запрос передаётся id карточки, например kwaivgi/kling-video-o1, а не название из красивого заголовка. Значения operation следует брать из подтверждённых возможностей модели.

Если часть метаданных отсутствует, не объявляйте модель ни бесплатной, ни безусловно готовой. В результате jq такие значения могут быть null. Найдите точную карточку и проверьте схему и оценку по /v1/media. Метаданные помогают найти кандидата, а исполнимый входной контракт определяется схемой выбранной модели и режима.

curl --fail-with-body --silent --show-error \
  "https://api.celestriagate.com/api/v1/catalog/models" \
  --output catalog.json

jq '[.data[] | select(.native_generation.schema_path == "/v1/media/models/schema") | select((.capabilities.output_modalities // []) | index("video")) | {id, display_name, operations: ([.native_generation.variants[]? | .operation] | unique), available: .native_generation.available, unavailable_reason: .native_generation.unavailable_reason}]' catalog.json

Что означает available и почему карточка может быть заблокирована

Поле native_generation.available описывает текущую готовность карточки, если такой блок есть; отдельные variants могут иметь собственные available и unavailable_reason. Лицензия, подходящий транспорт, подтверждённая схема и рублёвый расчёт влияют на возможность запуска. Заявленный видеовыход сам по себе не доказывает, что каждый режим модели готов выполнить произвольный заказ.

Причину недоступности показывайте человеку понятным текстом. Для license_unknown требуется подтверждение лицензии; для training_endpoint_unsupported нужен иной тип работы, потому что обучение не является обычной генерацией. pricing_verification_required означает ожидание проверки цены, schema_unavailable — невозможность подтвердить схему. Эти причины относятся к готовности маршрута; клиентский порядок остаётся общим: схема, оценка, задание и получение по ID.

Часть схем и тарифов проверяется по мере выбора модели. Поэтому после успешного чтения конкретной схемы состояние может измениться. Не выводите жёсткий рекламный счётчик «все готовы» из числа исходных записей. Лучше показывайте, какие варианты доступны сейчас, и объясняйте, почему остальные ожидают проверки.

Проверьте поля операции, а не всего семейства

Передайте канонический model и обязательную operation в GET /v1/media/models/schema. Например, у Kling 3 Pro режим text-to-video отличается от работы с изображением. Схема сообщает, какие настройки возможны, какие значения допустимы и что относится к модельному объекту parameters. Путь API сохраняется при смене семейства.

Общие поля располагаются прямо в input: prompt, image_urls, video_url, duration, resolution, aspect_ratio и звуковые настройки, если они есть в схеме. duration — число. Дополнительные camera_fixed, enable_safety_checker или num_frames передавайте только в input.parameters и только для модели, которая их поддерживает. Перенос формы на новую модель начинается с новой схемы, а не с незаметного удаления неподходящих значений.

Особое внимание уделите исходникам: одна фотография может быть первым кадром, другая модель принимает набор референсов, а редактирование требует исходного видео. Одинаковый массив ссылок ещё не гарантирует одинаковый смысл. Подпишите поля в форме так, чтобы пользователь понимал роль каждого материала.

Отбирайте по цене только после проверки совместимости

После схемы проверьте тот запрос, который действительно собираетесь отправлять. Для общего маршрута доступен POST /v1/media/estimate; он не создаёт генерацию. Оценка учитывает совместимость конкретных параметров и возвращает предварительную цену. Выбор без звука нельзя представлять как цену такого же ролика со звуком.

Для каждой выбранной модели используйте тот же POST /v1/media/estimate с каноническим ID и input.operation. Если нужная формула пока не подтверждена, цена может быть неизвестна. Не заменяйте её произвольным ручным тарифом. Единицы и поддерживаемые условия определяет сервер по модели и запросу; клиент передаёт реальные параметры заказа.

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

Покажите модели в существующем чате без дублей

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

После выбора режима покажите только релевантные исходники и параметры. Для text-to-video достаточно описания; для редактирования нужны роли видео и фото. Не скрывайте неподдерживаемый обязательный параметр ради успешной отправки. Если выбранная комбинация не выполняется, сообщите причину до генерации и предложите осмысленное изменение заказа.

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

Обновляйте каталог так, чтобы не ломать старые заказы

Новые модели и тарифы появляются, прежние версии могут уйти из доступного списка. Обновление выбора не должно переписывать историю выполненных заказов. Вместе с каждым заданием сохраняйте канонический model, operation, тело запроса и фактически выбранный provider. Старую карточку можно пометить недоступной для новых запусков, сохранив историю результатов.

Проверку витрины начните с маленького набора известных сценариев: текстовая сцена, одна фотография, редактирование с видео. Для каждого убедитесь, что схема загружается, роль материалов верна, готовность объяснена и цена не выдаётся за итоговый расход. Эти чтения можно выполнить без платной генерации.

Затем отдельно проведите нужный реальный тест и зафиксируйте результат, провайдера и окончательный billing. Проверенный контракт не доказывает художественное качество, а один красивый ролик не доказывает готовность всех моделей. Такой порядок позволяет расширять каталог постепенно, сохраняя полезный выбор и понятные ожидания.

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

Почему в каталоге много моделей, но не все запускаются?

Каталог сохраняет активные исходные записи. Коммерческий запуск дополнительно зависит от схемы, тарифа, лицензии и доступного транспорта; причину показывает unavailable_reason.

Можно ли фильтровать только по слову Kling или Wan?

Это помогает найти семейство, но не отличает операции и версии. Для окончательного выбора нужны полный ID, входные материалы и схема конкретного режима.

available: true гарантирует нужный результат?

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

Как не потерять модели, которых нет у второго провайдера?

Сохранять все доступные канонические карточки Gate независимо от числа совместимых поставщиков. Для модели с одним маршрутом используется тот же /v1/media; причина only_compatible_route объяснит выбор без переключения API клиентом.

Источники

• Документация Celestria Gate
• Текущий общий каталог Gate
• Тарифы моделей fal
• Подтверждённые расходы fal: Billing Events
• Официальный справочник jq