API операций с видео

Обычный активный API-ключ и ваши текущие права определяют доступные модели, маршруты и операции. История принадлежит разрешённой комбинации владельца, исполнителя, выбранного ключа и группы. Другой ключ не наследует этот доступ. Также действуют ограничения домена и IP. Хост API в примерах — https://api.model-gate.com; при необходимости используйте включённый хост текущего профиля сервиса или собственного домена. Не используйте временное браузерное разрешение как ключ CLI.

Методы

Это специализированные методы видео сервиса. Создание и расчёт цены принимают JSON, а не multipart поставщика. Это ограниченный сценарий text/image-to-video, не универсальный проброс видео-SDK. Название протокола/модели не гарантирует текущую доступность; выбирайте предложение, которое каталог сейчас возвращает вашему ключу. Проверенные входные изображения описаны ниже. Remix, редактирование, отмена, синхронные видеоответы и генерация через общие Async/Batch здесь не поддерживаются.

Запрос и расчёт цены

Обязательные поля: model и непустой prompt. seconds — строка с десятичным целым числом. В зависимости от предложения выходные параметры задаются поддерживаемым size (WIDTHxHEIGHT), сочетанием resolution и aspect_ratio либо только aspect_ratio; не смешивайте формы. Предложения с длительностью и соотношением сторон не принимают размер в пикселях или разрешение. Пропущенные настройки используют явные значения по умолчанию предложения. Поля запроса каталога, включая request.prompt_max_chars, определяют допустимый ввод. Неподдерживаемые настройки, повторяющиеся JSON-ключи, неизвестные поля, двоичные/multipart-входы и слишком большое JSON-тело отклоняются. Предел JSON — 12 MiB вместе с base64-входами; профиль сервиса может быть строже. Читайте max_request_bytes в каталоге.

Необязательный model_gate: route_id указывает предложение из каталога; async допускает только true, поскольку операция всегда асинхронна; quote_sha256 — 64-значный шестнадцатеричный хеш из расчёта цены. Значение async=false не означает бесконечное ожидание.

Отправьте те же настройки в POST /v1/videos/quote. Ответ содержит route_id, model, quote, quote_sha256, charged:false и provider_health_verified:false. Генерация, списание и резервирование не создаются. Цена рассчитывается по указанному тарифу за завершённое видео или секунду с текущими применимыми коэффициентами. Источник длительности и отличие предварительной оценки от итоговой суммы описаны ниже. Размер файла не влияет на цену. Обновление quote не отправляет платный запрос.

Для явного подтверждения цены сохраняйте возвращённый хеш в запросе создания. Playground не отправляет max_cost_usd. Изменившийся ценовой контекст отклоняется с video_quote_changed. Quote не резервирует рабочие ресурсы и не гарантирует будущий успех поставщика.

# A paid action: choose model and settings that your catalog actually offers.
curl --fail-with-body 'https://api.model-gate.com/v1/videos' \
  -H "Authorization: Bearer $MODEL_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-video-0001' \
  --data '{"model":"YOUR_ALLOWED_VIDEO_MODEL","prompt":"A small paper boat on still water","seconds":"4","size":"1280x720","model_gate":{"async":true}}'

Длительность и размеры выше — пример, не универсальная гарантия модели. Копирование не выполняет команду. Выполнение может привести к списанию. Не добавляйте автоматический --retry к платному созданию.

Предварительная оценка и итоговая стоимость

Перед созданием операции проверяйте quote.kind:

Для предложений, у которых quote.duration_source равен original_mp4, предварительная посекундная оценка использует запрошенную длительность. Итоговая стоимость рассчитывается по измеренной длительности исходного проверенного MP4, которая может отличаться от запрошенной. Итоговое usage.seconds — точная десятичная строка, допускающая долю секунды; входное seconds остаётся строкой с целым числом. Тариф за завершённое видео сохраняет фиксированную цену за это одно видео. Отдельное поле quote.usage_kind описывает оценку Usage Limit: у неё может быть собственная предварительная или итоговая сумма. У остальных предложений сохраняется прежний расчёт по проверенной длительности из ответа о завершении.

Запрос создания с model_gate.max_cost_usd при quote.kind=estimate возвращает HTTP422 и video_cost_ceiling_not_guaranteed до платной генерации, даже если предварительная оценка ниже заданного потолка. Для фиксированной цены действует обычная проверка потолка. Если интеграции необходим жёсткий предел стоимости, выберите предложение с фиксированной ценой. quote_sha256 подтверждает выбранные настройки и ценовой контекст; он не превращает предварительную длительность в гарантированный максимум. Отсутствующее или некорректное видео не приводит к выдуманной нулевой длительности или повторной генерации.

Идентичность и жизненный цикл

Создание требует одного Idempotency-Key: 1–128 печатных символов ASCII без пробелов. Тот же ключ и неизменное проверенное намерение возвращают существующую операцию; изменённое намерение — 409. Идентичность включает модель, prompt, нормализованные настройки, явный маршрут и ценовые условия. Сохраняйте тот же ключ и контекст сотрудника; новый ключ или намерение — не безопасный повтор платной операции с неизвестным исходом. Записи сохраняются после истечения файлов.

Принятое создание возвращает HTTP202, Location и локальный ID операции. Повтор уже завершённого намерения может вернуть 200 с той же операцией, а не новым видео. Проверяйте status: HTTP200 при чтении или 202 при принятии в очередь не означает завершение у поставщика.

Состояния: queued, preparing, dispatching, received, polling, retrieving, completed. Быстрые этапы могут не попасть в наблюдение; не каждое предложение проходит этап опроса. Принятая операция может ожидать ответ на этапе отправки, а затем перейти непосредственно к получению и проверке результата. provider_progress отсутствует, если недоступен; иначе это процент поставщика, а не прогноз времени завершения. Явный режим деталей может включать supplier_http_status и last_poll_http_status; в компактном ответе их нет. Закрытие страницы не отменяет принятую операцию.

После неоднозначного создания автоматического платного повтора нет. outcome_unknown требует поддержки; review_required означает необходимость проверки сохранённых данных; retrieval_failed — невозможность получить или проверить уже сгенерированный результат. Ошибка скачивания не разрешает генерацию заново. Ограниченные проверки могут остановиться с video_poll_deadline; это не гарантирует, что поставщик прекратил работу. Сообщите ID операции и безопасный код вместо отправки дубликата.

История, MP4 и доступ

GET /v1/videos/operations возвращает до 50 записей в разрешённой области с next_cursor; для более старых записей передавайте его как before. ?idempotency_key=... выполняет поиск без записи и возвращает submission_found. Временное отсутствие не доказывает, что выполняющийся запрос создания ничего не сделал.

Детали/результат завершённой операции содержат описание файла: MIME, байты, SHA-256, размеры и длительность. /result — JSON-описание. /content — фактический закрытый video/mp4, поддерживающий разрешённые Range-запросы и ?download=1; он не генерирует новое видео. Каждое чтение требует действующих прав. Результат — MP4 с H264 и необязательным AAC; предложения ограничены 30 секундами, 4096 пикселями по каждой стороне и 128 MiB и могут иметь более строгие пределы. Обычно файлы истекают через 24 часа после создания. Чтение отсутствующего, просроченного или повреждённого содержимого не генерирует его заново.

У операции может быть записанная цена даже при последующей ошибке скачивания файла. В явном режиме деталей accounting_recorded означает наличие входной записи для расчёта, а не завершённое списание. Наблюдение settlement различает ожидание, settled/recovered, недоступность и отсутствие сохранённой записи. Подпись Debited используется только при фактически найденной положительной сумме settled/recovered; Usage Limit отличается от денег на балансе. Старые строки результата/расчёта могут быть уже недоступны. Чтение оплаченного результата не требует положительного текущего баланса, но текущие права обязательны.

Ошибки и диагностика

Типичные ошибки входа: 400 — неверные поля/идемпотентность, 403 — отозванная область доступа или изменённое тело разрешения, 409 — конфликт идемпотентности, 413 — слишком большой JSON, 415 — неверный Content-Type, 422 — неподдерживаемые настройки или изменившийся quote, 429 — ресурсы/лимиты, 503 — недоступный каталог/сервис. Проверяйте безопасный error.code, не считая каждый 503 доказательством отсутствия работы. Непустой error_code операции сопровождает её сохранённое состояние и может отражать ошибку поставщика даже при GET статуса с 200.

Raw response в Playground показывает фактически полученный ответ сервиса, включая ошибки и пробелы, а не секретные заголовки поставщика. Исходные данные должны оставаться закрытыми. Для поиска операции поддержкой не требуется публично публиковать prompt, ключ или загруженный ответ.

Настройки вывода конкретного маршрута

Некоторые доступные маршруты принимают resolution и aspect_ratio вместо size. Проверьте выбранный маршрут в GET /v1/videos/catalog; не сочетайте эти поля с size. В этом API seconds остаётся строкой. Каталог содержит допустимые значения и значения по умолчанию. Неподдерживаемые входные изображения и референсы отклоняются, а не пропускаются незаметно.

{"model":"YOUR_AVAILABLE_VIDEO_MODEL","prompt":"A paper boat on a quiet lake","seconds":"6","resolution":"720p","aspect_ratio":"16:9","model_gate":{"async":true}}

Отправьте это тело в POST /v1/videos API текущего аккаунта со своим API-ключом и одним сохранённым Idempotency-Key. Сначала рассчитайте цену для тех же параметров через POST /v1/videos/quote; изменение параметров делает прежний расчёт недействительным. Совместимый маршрут может разрешать 1–15 секунд и часть перечисленных ниже разрешений; доступные вам варианты определяет выбранный каталог, а не этот пример. Результатом остаётся сохранённый MP4 с проверкой доступа; сторонние URL результатов не являются публичными ссылками скачивания для клиента.

Предложения с выбором разрешения могут предоставлять 480p, 720p, 1080p, 1440p, 2160p, 2k, 2K, 4k или 4K. Используйте только точное значение из request.resolutions выбранного предложения: доступность зависит от модели и вашего аккаунта. Здесь 2k/2K обозначают короткую сторону 1440 пикселей, а 4k/4K — 2160 пикселей, а не ширину DCI. Написание и регистр сохраняются в запросах расчёта цены и создания. После расчёта цены нельзя заменять значение его алиасом: выберите предлагаемый вариант и получите для него новый quote. Допустимые обозначения не гарантируют, что каждая модель предоставляет все разрешения.

Только длительность и соотношение сторон

Другие текстовые предложения принимают seconds и aspect_ratio без size и resolution. Поля image и reference_images для них запрещены. Настройки запроса в каталоге содержат request.seconds, request.default_seconds, request.aspect_ratios и request.default_aspect_ratio. Такие предложения могут предоставлять длительности от 1 до 20 секунд и соотношения сторон 16:9, 9:16, 1:1, 4:3 и 3:4; конкретная модель может разрешать только часть значений. Используйте возвращённые списки и значения по умолчанию.

{"model":"YOUR_AVAILABLE_VIDEO_MODEL","prompt":"A paper boat on a quiet lake","seconds":"4","aspect_ratio":"16:9","model_gate":{"route_id":"YOUR_OFFERED_ROUTE","async":true}}

Создание по-прежнему выполняется через POST /v1/videos и возвращает асинхронную локальную операцию. Если поле model_gate.async передано, оно остаётся true. Читайте статус этой операции и сохранённый результат методами выше; настройки длительности и соотношения сторон не требуют другого способа отправки клиентского запроса.

Краткий статус и детали расчёта

Начиная с версии 11.0.0, ответы операций по умолчанию компактны: object, id, model, status, created, status_url, result_url. Значимый error_code или сообщённый прогресс включается только при наличии. Завершённые результаты содержат доступность, срок действия и необходимые описания файлов. Пустые поля, расчёт цены, нормализованное usage, settlement и диагностика поставщика опускаются. Отсутствие поля не означает нулевую стоимость или завершённое списание.

Для прежнего полного разрешённого представления расчёта используйте GET /v1/videos/operations/{id}?view=details. Списки и перечни результатов также поддерживают явный режим деталей там, где применимо. Чтение деталей не создаёт медиа и не расширяет доступ. Quote остаётся отдельным эндпоинтом проверки цены без списания.

Необязательные входные референсы

Сначала прочитайте объект request.reference_images выбранного предложения. modes, max_images, mime_types, max_image_bytes, max_total_bytes и max_pixels обязательны к соблюдению. Отсутствие объекта означает только текстовый ввод. Используйте image для первого кадра либо reference_images для набора, но не оба. Принимаются только встроенные data URL PNG/JPEG/WebP; внешние URL и ID файлов не принимаются. Сервер проверяет фактическое растровое содержимое. Некоторые предложения первого кадра требуют точного совпадения с выбранными размерами вывода.

{"model":"YOUR_ALLOWED_VIDEO_MODEL","prompt":"A calm scene","seconds":"6","resolution":"720p","aspect_ratio":"16:9","image":{"url":"data:image/png;base64,REPLACE_WITH_IMAGE_BYTES"},"model_gate":{"route_id":"YOUR_OFFERED_ROUTE","async":true,"quote_sha256":"YOUR_QUOTE_FINGERPRINT"}}

Для поддерживаемого набора референсов замените image на "reference_images":[{"url":"data:image/png;base64,..."},{"url":"data:image/jpeg;base64,..."}]. Примеры с заполнителями нельзя выполнить без замены данных. Сначала рассчитайте цену с точно теми же входами и настройками, сохраните хеш и один Idempotency-Key для создания. Режимы входа могут иметь разные тарифы; одно название модели не включает поддержку референсов.

Чтение результата: Raw и cURL

Используйте тот же активный API-ключ и контекст пользователя, с которыми создана операция. Другой ключ того же аккаунта не наследует результат автоматически. Текущие права и ограничения домена/IP проверяются снова. Возьмите OPERATION_ID из ответа принятой операции или разрешённой истории, а MODEL_API_KEY задайте локально, не публикуя секрет. Временное разрешение Playground не является многократно используемым CLI-ключом; копирование команды не экспортирует и не расширяет это разрешение.

GET https://api.model-gate.com/v1/videos/operations/{id}/result
Authorization: Bearer <YOUR_API_KEY>

# status
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/videos/operations/${OPERATION_ID:?Set OPERATION_ID}" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output video-status.json

# result
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/videos/operations/${OPERATION_ID:?Set OPERATION_ID}/result" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output video-result.json

# MP4
curl --fail-with-body --request GET \
  --url "https://api.model-gate.com/v1/videos/operations/${OPERATION_ID:?Set OPERATION_ID}/content" \
  --header "Authorization: Bearer ${MODEL_API_KEY:?Set MODEL_API_KEY}" \
  --output video.mp4

/result — JSON-описание. Для сохранения самого видео используйте /content и имя .mp4. Сохранение описания как .mp4 не превращает его в видео. Локальный ID операции — идентификатор этого API, не задания поставщика.

Это GET-запросы без тела: не нужны Content-Type, Idempotency-Key, расчёт цены, route_id или max_cost_usd. Читайте статус до завершения, затем результат/файл. Ответы ожидания, ошибки, истёкшего срока и отказа в доступе — не выходные файлы; --fail-with-body возвращает ненулевой код при HTTP-ошибке, но может записать её тело под выбранным именем. Проверяйте статус и тип содержимого, прежде чем считать загруженное тело медиафайлом. Не повторяйте платный POST из-за ошибки GET.

Блок Playground Get the result · Raw / cURL формирует эти команды для выбранной операции и её исходного ключа. Это примеры нового чтения, а не запись прежнего HTTP-обмена. Копирование и переключение вкладок команд не отправляют сетевых запросов. Открытие истории или сохранённого результата выполняет обычное разрешённое чтение, но не новую генерацию, резервирование или списание.