API видео проекта

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

Методы

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

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

Обязательные поля: model и непустой prompt. seconds — строка с десятичным целым числом. В зависимости от предложения выходные параметры задаются поддерживаемым size (WIDTHxHEIGHT) либо сочетанием resolution и 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.b2b-llm.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 к платному созданию.

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

Создание требует одного 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. seconds остаётся строкой в этом API. Допустимые значения и значения по умолчанию возвращает каталог. Неподдерживаемые входные изображения или референсы отклоняются, а не опускаются незаметно.

{"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 рабочей области с разрешённым ключом проекта и одним сохраняемым Idempotency-Key. Сначала рассчитайте те же параметры через POST /v1/videos/quote; изменение параметров делает предыдущий quote недействительным. Совместимый маршрут может разрешать 1–15 секунд и 480p/720p, но допустимые варианты определяет выбранный каталог, а не пример. Результат остаётся закрытым сохранённым MP4; сторонние URL результата не являются публичными клиентскими ссылками скачивания.

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

Начиная с версии 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

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

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

# status
curl --fail-with-body --request GET \
  --url "https://api.b2b-llm.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.b2b-llm.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.b2b-llm.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-обмена. Копирование и переключение вкладок команд не отправляют сетевых запросов. Открытие истории или сохранённого результата выполняет обычное разрешённое чтение, но не новую генерацию, резервирование или списание.