Clipwright

API Clipwright

Единый HTTP API, который превращает сценарий в UGC-видео с синхронизацией губ или сценарий либо краткое описание — в видео без лица: закадровая озвучка поверх вступительного анимированного клипа и сцен с изображениями. API создан для управления агентом: каждый вызов — это один JSON-запрос, в каждом отказе указано, что делать дальше, и ничего нигде не публикуется. Весь текст этой страницы также содержится в одном файле Markdown по адресу https://clipwright.io/docs.md и в кратком контракте для агентов по адресу https://clipwright.io/llms.txt, предназначенном для агентов, которые читают текст. Файл OpenAPI 3.1 по адресу https://api.clipwright.io/openapi.json — это машиночитаемый контракт REST API, созданный на основе схем, по которым API проверяет данные.

Аутентификация

Каждый вызов отправляется на https://api.clipwright.io и передаёт ключ в одном заголовке:

Authorization: Bearer cw_your_key_here

• Ключи начинаются с cw_ и показываются один раз при выдаче. Мы храним только дайджест, поэтому утерянный ключ заменяют, а не восстанавливают.
• Выпускайте и отзывайте ключи в https://app.clipwright.io/api-keys на панели управления. Отзыв вступает в силу со следующего запроса.
• @clipwright/cli и @clipwright/mcp-server считывают ключ из переменной окружения CLIPWRIGHT_API_KEY; @clipwright/sdk принимает его как аргумент.
• Запрос без ключа или с отозванным ключом отклоняется с кодом 401 до списания средств.

03

Стоимость

• make_ugc с обычным сценарием: 10 кредитов за каждую секунду готового видео, с округлением вверх до целой секунды; минимум 50 кредитов за доставленное видео.
• make_ugc с сегментами или вставками: 9 кредитов за каждую секунду, когда лицо находится на экране (22 за дубль, отрендеренный на OmniHuman), плюс 1 кредит за каждую секунду видео и 400 за каждый кадр вызова live-avatar; минимум 50 кредитов за доставленное видео. Лицо, закрытое вставкой, наложением, окном или шаблоном, всё равно учитывается, а запуск, не доставивший файл, ничего не стоит. Время показа лица суммируется по всему видео и округляется вверх один раз, а не для каждого сегмента. Для этих полей требуется доступ к длинному формату; если он отключён, запросы с ними отклоняются с указанием имени поля до списания средств.
• create_actor с качеством medium: 4 кредита за портрет (ничего, если используется ваше изображение, переданное в portrait; 4 за представление существующего актёра, созданное с помощью from_actor_id) и 8 за каждый дополнительный формат.
• create_actor с качеством high: 45 кредитов за портрет (ничего, если используется ваше изображение, переданное в portrait; 12 за представление существующего актёра, созданное с помощью from_actor_id) и 18 за каждый дополнительный формат.
• make_faceless: 7 кредитов за каждое созданное нами изображение, 49 за вступительный клип и 1 за каждую секунду доставленного видео; минимум 50. Расчёт для указанного вами duration_seconds — это максимальная сумма к оплате: 212 кредитов за 30 секунд, 356 за 90. За ваши изображения плата не взимается, а субтитры не влияют на цену.
• Кредиты продаются пакетами: 1000 кредитов за $10.00, 2750 кредитов за $25.00, 6000 кредитов за $50.00. Один пакет на платёж, без подписки.

Уточните стоимость до запуска: запрос цены для каждого навыка ничего не стоит. Ценность ответа зависит от навыка.

• make_ugc: расчёт — это оценка по словам сценария. Сумма к оплате определяется по готовому видео: по его длительности для обычного сценария или по времени показа лица для сценария с лицом. Поэтому итоговый счёт может быть как выше, так и ниже расчёта.
• create_actor: расчёт включает все запрошенные форматы и показывает максимальную сумму к оплате. Вы платите за портрет и фактически опубликованные варианты; формат, который не был создан, указывается в warnings[] и ничего не стоит.
• make_faceless: расчёт включает указанное вами значение duration_seconds и показывает максимальную сумму к оплате. Длительность видео определяется временем, необходимым для озвучки: не менее 25 секунд (для поясняющего видео — только его озвучка), обычно не более чем на четверть дольше этой длительности и не более 90 секунд; более длинная озвучка воспроизводится до конца. Вы платите за фактически доставленную длительность, но не больше расчётной суммы.

Стоимость неудачного запуска также зависит от навыка:

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

04

Стоимость редактирования

Редактирование видео без лица запускает новую обработку на основе изменённого документа: POST /v1/runs/{id}/revisions/quote рассчитывает стоимость бесплатно, POST /v1/runs/{id}/revisions запускает обработку.

• Новое изображение: 7 кредитов.
• Новый вступительный клип: 49 кредитов.
• Новый вступительный кадр и клип к нему: 56 кредитов.
• Рендеринг редакции, в которой что-либо создаётся: 13 кредитов за редакцию.
• Рендеринг редакции, в которой ничего не создаётся (изменение тайминга, удаление или ваша собственная загрузка): 13 кредитов.
• После включения платного редактирования исходный материал можно редактировать за плату в течение 364 дней после завершения обработки.
• Одновременно может выполняться не более 1 редакции одного исходного материала. Неудачных или незавершённых редакций может быть не более 3.
• За доставленную редакцию списывается рассчитанная сумма; неудачная редакция ничего не стоит.
• Пока платное редактирование отключено, оба маршрута редакций возвращают editing_disabled и ничего не списывают.

05

Стоимость вариантов кадров

Вариант кадра — это одно изображение или клип, созданный для одного кадра видео без лица, который можно оставить или удалить при редактировании: POST /v1/runs/{id}/candidates/quote рассчитывает стоимость бесплатно, POST /v1/runs/{id}/candidates создаёт вариант.

• Вариант изображения: 7 кредитов.
• Вариант вступительного клипа: 49 кредитов.
• Вариант вступительного кадра и клипа к нему: 56 кредитов.
• Одновременно может выполняться не более 1 создания вариантов кадров для одного исходного материала. Неудачных или незавершённых созданий может быть не более 3. Редакции учитываются отдельно.
• За доставленный вариант списывается стоимость одной единицы независимо от того, оставите вы его или удалите; неудачный вариант ничего не стоит.
• Пока создание вариантов кадров отключено, три маршрута вариантов возвращают editing_disabled и ничего не списывают.

06

Конечные точки

Конечная точка	Списывает кредиты	Назначение
POST /v1/skills/make_faceless/quote	нет	Рассчитывает стоимость вызова make_faceless с этими входными данными. Ничего не списывает.
POST /v1/skills/make_faceless/run	да	Запускает создание видео без лица и сразу возвращает run_id. Опросите запуск, чтобы получить результат.
GET /health	нет	Проверяет работоспособность самого API. Отвечает без ключа.
GET /	нет	Указывает название сервиса и ссылку на этот документ. Отвечает без ключа.
GET /robots.txt	нет	Указывает поисковым роботам не индексировать хост API. Отвечает без ключа.
GET /openapi.json	нет	Описание этого API в формате OpenAPI 3.1, созданное на основе тех же схем, которые API использует для проверки данных. Отвечает без ключа.
GET /v1/voices	нет	Голоса, которые можно указать в voice или voice_id для make_ugc; при skill=make_faceless вместо них перечисляются голоса для озвучивания в make_faceless.
GET /v1/template-sounds	нет	Звуки, которые воспроизводят шаблоны make_ugc, по тактам: где воспроизводится каждый такт, его значение по умолчанию и все имена, которые принимает template_sounds. Бесплатно.
GET /v1/moves	нет	Каталог движений, которые можно назначить строкам сценария как moves в make_ugc, make_faceless и ремейке по референсу: что каждое движение даёт зрителю, для каких строк подходит и сколько кредитов стоит каждое использование; результаты можно фильтровать и просматривать постранично; параметр names возвращает полные строки. Бесплатно.
GET /v1/account	нет	Баланс, задолженность и удержания на счёте, связанном с ключом, а также наши ответы на обращения в поддержку и отзывы.
POST /v1/skills/make_ugc/quote	нет	Рассчитывает стоимость вызова make_ugc с этими входными данными. Ничего не списывает.
GET /v1/runs/{id}	нет	Состояние одного запуска любого навыка, его предупреждения и url видео.
GET /v1/runs/{id}/shots	нет	Кадры одного запуска: временной интервал, слова, описание и предпросмотр каждого кадра, а также возможность редактирования запуска.
GET /v1/runs/{id}/edit	нет	Сохранённый черновик правок одного запуска с его версией. Версия 0 означает, что у запуска нет черновика: документ ничего не меняет.
POST /v1/runs/{id}/edit	нет	Сохраняет черновик правок относительно версии, прочитанной ранее. Ничего не списывает и не рендерит.
POST /v1/runs/{id}/revisions/quote	нет	Рассчитывает стоимость правки запуска без лица: что будет создано по документу или списку изменений кадров и сколько это стоит. Ничего не списывает. За успешно выполненную правку списывается указанная в расчёте сумма; за неудачную — ничего. Пока платные правки недоступны, возвращает editing_disabled.
POST /v1/runs/{id}/revisions	да	Запускает правку — новый запуск без лица, созданный по документу, — и удерживает рассчитанное количество кредитов. Повторный запрос с тем же Idempotency-Key и теми же данными возвращает первую правку; другой ключ создаёт новую правку и приводит к повторному списанию. За успешно выполненную правку списывается указанная в расчёте сумма; за неудачную — ничего. Пока платные правки недоступны, возвращает editing_disabled и ничего не списывает.
POST /v1/runs/{id}/candidates/quote	нет	Рассчитывает стоимость одного варианта кадра для запуска без лица: изображения или клипа, созданного для одного кадра, который можно оставить или удалить. Ничего не списывает. За созданный вариант списывается стоимость одной единицы независимо от того, оставлен он или удалён; за неудачный вариант ничего не списывается. Пока варианты кадров недоступны, возвращает editing_disabled.
POST /v1/runs/{id}/candidates	да	Создаёт вариант кадра и удерживает стоимость одной единицы. За созданный вариант списывается стоимость одной единицы независимо от того, оставлен он или удалён; за неудачный вариант ничего не списывается. Повторный запрос с тем же Idempotency-Key, теми же данными и take возвращает первый вариант; take + 1 создаёт ещё один вариант с повторным списанием. Пока варианты кадров недоступны, возвращает editing_disabled и ничего не списывает.
GET /v1/runs/{id}/candidates	нет	Варианты кадров для семейства запусков без лица, от самого старого к самому новому; для каждого указаны состояние, списание и предпросмотр после создания. Пока варианты кадров недоступны, возвращает editing_disabled.
DELETE /v1/runs/{id}/media	нет	Удаляет файлы завершённого запуска: ссылки на них больше не предоставляются, а через 7 дней файлы удаляются из хранилища. Запуск и списание сохраняются. Запрос отклоняется с run_media_in_use, если эти файлы используются другим незавершённым запуском. Бесплатно.
POST /v1/skills/make_ugc/run	да	Запускает создание видео и сразу возвращает run_id. Опросите запуск, чтобы получить результат.
GET /v1/public/skills	нет	Каталог навыков и их входных данных, доступный без ключа.
GET /v1/public/prices	нет	Стоимость каждого действия в кредитах: фиксированная цена за единицу или формула, в которой цена зависит от входных данных; точное значение указывается в расчёте. Бесплатно, доступно без ключа.
GET /v1/actors	нет	Актёры, сохранённые в аккаунте, с id, который принимает make_ugc.
GET /v1/public/actor-previews/{actor_id}/{version}/{file}	нет	Изображение библиотечного актёра в формате PNG по ссылке, которую возвращают list_actors и расчёты стоимости. Отвечает без ключа.
DELETE /v1/actors/{id}	нет	Удаляет сохранённого актёра. Актёр, используемый активным запуском, сохраняется.
GET /v1/actors/{id}/defaults	нет	Читает сохранённую политику актёра по умолчанию для людей во вставках.
POST /v1/actors/{id}/defaults	нет	Задаёт сохранённую политику актёра по умолчанию для людей во вставках. Запуск может переопределить её.
GET /v1/brand-kit	нет	Читает сохранённый дизайн аккаунта: цвета, шрифты, логотип, углы и анимацию. Если дизайн не сохранён, возвращает null.
POST /v1/brand-kit	нет	Сохраняет дизайн аккаунта или удаляет его, если передано null. Видео, в котором не указаны ни дизайн, ни template_theme, будет оформлено в этом стиле. Бесплатно.
POST /v1/brand/extract	нет	Считывает цвета, шрифты, логотип и углы с общедоступного сайта и предлагает дизайн с читаемым текстом для вашего подтверждения. Бесплатно; учитывается в почасовом лимите загрузок по url.
POST /v1/skills/create_actor/quote	нет	Рассчитывает стоимость вызова create_actor с этими входными данными. Ничего не списывает.
POST /v1/skills/create_actor/run	да	Запускает создание актёра и сразу возвращает run_id. Опросите запуск, чтобы получить результат.
POST /v1/uploads	нет	Принимает байты изображения и возвращает подписанный https url, upload_id и content_digest (SHA-256 исходных байтов). Используйте upload_id как asset_id в рабочем процессе и скопируйте content_digest без изменений; в вызовах native video и actor используется url.
GET /v1/uploads	нет	Ваши загрузки, которые ещё принимает правка, от самых новых к самым старым, по одной на изображение; для каждой указаны upload_id, исходный content_digest, заново подписанный url и время, когда загрузка перестанет быть доступной. Бесплатно.
POST /v1/uploads/import	нет	Загружает общедоступный PNG или JPEG по https (до 10 MB, 20 секунд, 3 перенаправления) и возвращает объект загрузки той же формы. Запросы к частным адресам отклоняются; 30 загрузок в час на аккаунт. Бесплатно.
POST /v1/uploads/intents	нет	Возвращает предварительно подписанный PUT url для локального PNG или JPEG с указанными типом, размером и sha256. upload_id можно использовать после завершения PUT; до этого генерация возвращает upload_not_finished. Бесплатно.
GET /v1/uploads/{id}	нет	Одна загрузка с заново подписанным url и значением usable_until. После предварительно подписанного PUT подтверждает наличие файла: пока файл не загружен, возвращает upload_not_finished; через 24 часа — upload_expired. Бесплатно.
DELETE /v1/uploads/{id}	нет	Удаляет загрузку: новые вызовы больше не смогут её использовать, а через 7 дней файл удаляется из хранилища, если не сохранена другая загрузка того же изображения. Запрос отклоняется с upload_in_use, если загрузка используется незавершённым запуском. Бесплатно.
POST /v1/assets	нет	Сохраняет изображение как ресурс аккаунта, который хранится до удаления: из run_id, upload_id, общедоступного https url или base64. Для собственных материалов требуется rights_confirmed: true; для референса, сохраняемого только для analyze_reference, можно указать analysis_only: true — такой ресурс нельзя использовать для рендеринга или генерации. 2000 ресурсов и 1 GB на аккаунт; 20 GB после покупки кредитов; 100 новых ресурсов в день. Бесплатно.
POST /v1/assets/bytes	нет	Сохраняет PNG или JPEG из тела запроса (до 10 MB) как ресурс; role, name и rights_confirmed=true (или analysis_only=true, только для analyze_reference) передаются в query. Бесплатно.
GET /v1/assets	нет	Активные ресурсы аккаунта, от самых новых к самым старым; для каждого указана ссылка, действующая один час, а также использование лимитов. Фильтры role и kind, постраничная выдача с помощью cursor. Бесплатно.
GET /v1/assets/{id}	нет	Один активный ресурс со ссылкой, действующей один час. Бесплатно.
POST /v1/assets/{id}	нет	Переименовывает ресурс или меняет его роль. Бесплатно.
DELETE /v1/assets/{id}	нет	Удаляет ресурс: он сразу исчезает из списка и становится недоступен для генерации; ежедневная очистка удаляет его файл по истечении 7 дней. Бесплатно.
GET /v1/public/workflows	нет	Перечисляет общедоступные методы рабочих процессов и указывает, доступны ли они сейчас, без сведений о тарифах аккаунта и его допуске.
GET /v1/public/workflows/{id}	нет	Возвращает рекомендации и ограничения метода, а также сведения о том, что он может делать сейчас.
POST /v1/workflow-plans	нет	Создаёт неизменяемый черновик рабочего процесса, принадлежащий аккаунту. Ничего не списывает и не запускает рендеринг.
GET /v1/workflow-plans/{id}	нет	Возвращает текущую редакцию рабочего процесса аккаунта и её готовность.
POST /v1/workflow-plans/reference-remake	нет	Компилирует профиль референса и утверждённый сценарий в новый черновик ремейка по референсу; в предупреждениях указано, что план не воспроизводит. Ничего не списывает, не генерирует и не запускает рендеринг.
POST /v1/workflow-plans/{id}/revisions	нет	Сохраняет новый черновик относительно base_version. Повторный запрос после потери ответа с теми же данными возвращает эту редакцию.
POST /v1/workflow-plans/{id}/approve	нет	Утверждает готовую редакцию и её digest. Ничего не списывает и не запускает рендеринг.
POST /v1/workflow-plans/{id}/quote	нет	Рассчитывает стоимость утверждённого рабочего процесса с использованием native preparation. Расчёт истекает через пять минут; кредиты не резервируются. Для запуска используется готовое тело запроса на запуск с новым idempotency_key.
POST /v1/workflow-plans/{id}/run	да	Принимает в точности рассчитанный native-запрос один раз и возвращает квитанцию и существующий native Run. Передайте launch из расчёта без изменений в теле запроса, а в заголовке Idempotency-Key укажите значение launch.idempotency_key; повторный запрос с теми же данными возвращает тот же запуск.
GET /v1/generations/models	нет	Модели, которые принимают generate_image и generate_video, с измеренными режимами, соотношениями сторон, разрешениями, длительностью, размером результата и стоимостью в кредитах за изображение или секунду. Бесплатно. Пока генерация недоступна, возвращает generations_disabled.
POST /v1/skills/generate_image/quote	нет	Рассчитывает стоимость одного изображения по этому запросу: кредиты, ширина, высота и предупреждения. Ничего не списывает.
POST /v1/skills/generate_image/run	да	Запускает генерацию одного изображения и сразу возвращает run_id; после создания изображение доступно в блоке generation запуска. За неудачную генерацию ничего не списывается. Пока генерация недоступна, возвращает generations_disabled и ничего не списывает.
POST /v1/skills/generate_video/quote	нет	Рассчитывает стоимость одного клипа без звука по этому запросу: кредиты за секунду, умноженные на длительность, ширина, высота и предупреждения. Ничего не списывает.
POST /v1/skills/generate_video/run	да	Запускает генерацию одного клипа и сразу возвращает run_id; после создания клип доступен в блоке generation запуска. За неудачную генерацию ничего не списывается. Пока генерация недоступна, возвращает generations_disabled и ничего не списывает.
POST /v1/reference-analyses/quote	нет	Рассчитывает стоимость анализа этого ресурса или ссылки: 70 кредитов, 10 при mode data или 0, если уже есть действующий анализ в этом режиме. Ничего не списывает.
POST /v1/reference-analyses	да	Анализирует ресурс MP4 длительностью до 120 s и создаёт профиль референса (или, при mode data, расшифровку, хук и лист кадров), сразу возвращая ответ; для того же ресурса и режима возвращается тот же анализ бесплатно. Удерживает 70 кредитов (10 для data) и списывает их после успешного завершения; за неудачный анализ ничего не списывается. 10 новых полных и 60 новых анализов data в час.
GET /v1/reference-analyses/{id}	нет	Один анализ референса: в очереди, анализируется, завершён с reference_profile или data и предупреждениями либо завершился ошибкой с её описанием. Бесплатно.
POST /v1/creator-profiles/quote	нет	Рассчитывает стоимость профиля автора для этой ссылки: 20 кредитов или 0, если за последний час уже создан профиль того же автора. Ничего не списывает.
POST /v1/creator-profiles	да	Начинает анализ автора профиля или видео по ссылке Instagram или TikTok: его последние 12 видео с просмотрами, отметками «Нравится», комментариями и репостами, медианное число просмотров и показатель каждого видео относительно него. Результат возвращается сразу; запрос по тому же автору в течение часа возвращает тот же профиль бесплатно. Резервирует 20 кредитов, списываемых после успешного выполнения; за закрытый или пустой аккаунт, а также за любой сбой плата не взимается. 30 новых профилей в час.
GET /v1/creator-profiles/{id}	нет	Профиль одного автора: в очереди, анализируется, выполнен успешно с профилем и предупреждениями или завершился ошибкой с описанием ошибки. Бесплатно.
DELETE /v1/creator-profiles/{id}	нет	Немедленно удаляет готовый профиль автора; запуск, в результате которого он был создан, и списание сохраняются. Если профиль ещё создаётся, запрос отклоняется с run_not_finished. Бесплатно.
POST /v1/trend-searches/quote	нет	Рассчитывает стоимость поиска по теме: 20 кредитов или 0, если поиск по тому же запросу за последний час уже даст ответ. Ничего не списывает.
POST /v1/trend-searches	да	Начинает поиск роликов по теме: TikTok и Instagram ранжируются вместе, если не указана одна платформа; до 10 роликов на платформу, по одному от автора, каждый с числом просмотров относительно медианного показателя его автора. Результат возвращается сразу; запрос по той же теме в течение часа возвращает тот же результат бесплатно. Резервирует 20 кредитов, списываемых после успешного выполнения, в том числе если результаты найдены только на одной платформе (в warnings[] указывается другая); если ролики не найдены или произошёл сбой, плата не взимается. 10 новых поисков в час.
GET /v1/trend-searches/{id}	нет	Поиск по одной теме: в очереди, выполняется, выполнен успешно с роликами и предупреждениями или завершился ошибкой с описанием ошибки. sort позволяет просмотреть те же ролики в другом порядке. Бесплатно.
POST /v1/feedback	нет	Сообщает нам, чего не хватает, что непонятно, неверно или работает медленно; при желании можно указать запуск этой учётной записи. Мы читаем каждое сообщение. Бесплатно. Запрос с теми же типом, текстом и запуском в течение 24 часов возвращает тот же feedback_id; 20 в час.
Результат выполнения любого навыка можно получить по тому же адресу: GET /v1/runs/{id}. Он проходит через следующие состояния: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

GET /v1/runs/{id}?wait_seconds=N (не более 50) ожидает завершения запуска — успеха или ошибки, окончания ожидания либо разрыва соединения, поэтому между запросами не нужно делать паузу. Незавершённый запуск возвращает ответ с текущим состоянием.

07

Навыки и их входные данные

make_ugc. Запускает создание UGC-видео с синхронизацией губ. Актор задаётся параметром actor_id (сохранённый актор из list_actors) или изображением; в противном случае используется актор по умолчанию. Формат и разрешение определяются запросом и исходным материалом; по умолчанию используется 1080x1920. Субтитры включаются только ПО ЗАПРОСУ: сначала спросите пользователя. В описании поля, которое рендерер пока не поддерживает, указано NOT HONORED YET.

Сразу возвращает run_id; опрашивайте get_run с его poll.arguments, пока состояние не станет 'succeeded' (video_url) или 'failed'. Если видео для запуска со статусом 'failed' всё ещё создаётся, запуск может вернуться в состояние 'queued' и позднее завершиться успешно; об этом будет указано в warnings[]. attempt=2,3,… запускает НОВЫЙ процесс для тех же входных данных. Чтобы создать видео по образцу референсного ролика, используйте analyze_reference, а затем plan_reference_remake с его analysis_id.

Поле	Обязательное	Значение
script	необязательно	Слова, которые произносит актёр; обязательно, если segments не содержит произносимый текст. Для segments и вставок, привязанных к тексту, требуется подтверждение соответствия требованиям для длинных роликов на сервере. Ограничения script по модели речи: eleven_v3: 5000 символов; eleven_flash_v2_5: 10000 символов; eleven_turbo_v2_5: 10000 символов; eleven_v4: 5000 символов; gemini-3.8-flash-tts: 5000 символов. В подсчёт входят пробелы, аудиотеги и знаки ударения; эмодзи могут считаться за два символа. Теги пауз удаляются из текста, отправляемого в eleven_v4 и gemini-3.8-flash-tts, и не учитываются при подсчёте для этих моделей. Ограничения по количеству слов нет. Длительность и стоимость являются приблизительными, пока не будут измерены. Русское ударение: обозначайте ударную гласную заглавной буквой внутри слова, написанного строчными буквами («потОм», «зАмок»); eleven_v4 и gemini-3.8-flash-tts получат её как знак ударения U+0301 («пото́м»); знак, введённый напрямую, сохраняется. Заглавная буква в начале слова остаётся заглавной, а слово со второй заглавной буквой или заглавной согласной внутри (все буквы заглавные, «ВУЗы») остаётся без изменений. Одна заглавная гласная внутри слова всегда воспринимается как знак ударения, поэтому пишите «Яндекс Еда», а не «ЯндексЕда». Сообщайте пользователям, пишущим по-русски, что они могут обозначать ударение таким способом. eleven_flash_v2_5 и eleven_turbo_v2_5 стоят дешевле, но неверно обрабатывают знаки ударения: заглавные буквы передаются им без изменений.
segments	необязательно	Упорядоченные сегменты с актёрами и изображениями; требуется подтверждение соответствия требованиям для длинных роликов на сервере, captions=false и 1080p. Для медиа с изображениями необходимо явно указать broll_policy=anyone.
inserts	необязательно	Вставки изображений или видео, привязанные к тексту и накладываемые на всю озвучку; каждая охватывает cover_words произнесённых слов, начиная с привязки; требуется подтверждение соответствия требованиям для длинных роликов на сервере, 1080p и явное указание broll_policy=anyone. Субтитры отображаются поверх вставок.
overlays	необязательно	Изображения или видео, привязанные к тексту и накладываемые поверх видимого ведущего; каждое размещается в одной позиции или области. Одновременно на экране может быть не более 2 таких элементов, и их области не должны пересекаться. Субтитры перемещаются в среднюю или нижнюю треть экрана, за пределы области наложения, но никогда не поверх лица; они скрываются, если свободной области нет. Скрываются под полноэкранными вставками. Требования те же, что и для inserts: script, подтверждение соответствия требованиям для длинных роликов на сервере, 1080p и явное указание broll_policy=anyone. Ведущий остаётся на экране, поэтому стоимость не меняется.
layout_windows	необязательно	Изменение кадрирования ведущего, привязанное к тексту: split (только 9:16) или card. Области не должны пересекаться друг с другом или со вставкой. Требования те же, что и для inserts. Даже если ведущий закрыт или размыт, это всё равно оплачиваемая работа поставщика, учитываемая как время показа лица.
framing	необязательно	Размеры ведущего, привязанные к тексту: для каждого элемента кадр переключается на крупный или средний план на соответствующих словах и возвращается к исходному плану после них. Элементы не должны пересекаться друг с другом, со вставкой или с окном макета. Кадрирование, полностью скрытое полноэкранными шаблонами, указывается в warnings[]. Если акцент punch_in совпадает с кадрированием, применяется кадрирование. Требуются script и подтверждение соответствия требованиям для длинных роликов на сервере; стоимость не меняется.
templates	optional	Графические шаблоны, каждый в формате { id, kind, anchor, cover_words?, placement?, transition?, data }. При каждом запуске сценария. Шаблоны никогда не меняют цену: каждый запуск тарифицируется по составляющим, как указано в list_prices, а время ведущего, покрытое шаблоном, всё равно считается временем ведущего. Идентификаторы уникальны для inserts, overlays, layout_windows и templates. Текст — одна строка латинскими буквами или буквами самого сценария, цифрами и распространёнными знаками препинания, без эмодзи; широкий иероглиф CJK считается за 2 символа при подсчёте лимита, а длинный текст уменьшается, чтобы поместиться в ширину соответствующего типа. size small|medium|large задаёт масштаб типа; по умолчанию используется medium. Поле media принимает { asset_id } готового ресурса указанного в нём типа. Внутренняя цитата указывает слова внутри текста самого шаблона, следующие за предыдущим таким фрагментом: её бит приходится на первое из этих слов и не должен попадать под insert или полноэкранный шаблон; щелчок или шаг без такой цитаты распределяется равномерно. Если бит произносится до появления шаблона, он переносится сразу после его появления, с предупреждением. Шаблон, пересекающийся с полосой субтитров, скрывает субтитры на время показа; шаблон в другом месте, например небольшой шаблон вверху, оставляет их видимыми. Полноэкранный шаблон также скрывает ведущего, overlays и шаблоны поверх ведущего на время показа, никогда не пересекается с wipe- или zoom-вставкой, а время ведущего, которое он закрывает, тарифицируется. Одновременно могут показываться не более 3 overlays и шаблонов поверх ведущего; их области не должны пересекаться. template_theme задаёт общий стиль для всех них. Типы: tag (over): короткая градиентная плашка поверх ведущего или insert; если position не задан, она располагается в области субтитров и скрывает их на время показа; data text ≤ 32, position? top|center|bottom, size? small|medium|large. lower_third (over): плашка с именем и должностью в нижней части кадра; субтитры скрыты на время показа; по умолчанию используется стиль clean_bar; data name ≤ 28, role? ≤ 36, side left|right, style? clean_bar|side_rule|soft_pill|mask_reveal, size? small|medium|large. end_card (over): плашка с сайтом и необязательным призывом к действию в области субтитров; субтитры скрыты на время показа; data site ≤ 32, cta? ≤ 48, size? small|medium|large. title_card (full): полноэкранная карточка-завязка: заголовок (до двух строк) на белой карточке рядом с необязательным изображением логотипа и необязательной плашкой под ним; data title ≤ 48, chip? ≤ 32, logo? {asset_id} image, size? small|medium|large. quote (full): полноэкранная карточка с цитатой: кавычки, текст (до четырёх строк), затем автор с необязательной круглой фотографией, обрезанной по кругу; data text ≤ 120, author? ≤ 32, photo? {asset_id} image (обрезается по размеру), size? small|medium|large. stat (full|over): число, увеличивающееся от 0 до value (до 2 знаков после запятой), с префиксом и суффиксом вокруг него и подписью под ним; full заполняет кадр, over располагается на уровне груди на карточке; data value number, prefix? ≤ 6, suffix? ≤ 6, label? ≤ 32, size? small|medium|large. callout (over): стрелка или кольцо, указывающее на точку кадра и пульсирующее; target {x,y} в % кадра от его верхнего левого угла, с необязательной плашкой-подписью под ним или над ним; может указывать на лицо, а подпись по возможности не закрывает его; также поверх insert; data target {x,y}, style arrow|ring, text? ≤ 24, size? small|medium|large. checklist (over): 2–4 строки, каждая с необязательной иконкой, подписью и переключателем или флажком в положении «вкл.» или «выкл.»; курсор по очереди нажимает на строки (item — индекс строки, начиная с 0), каждый щелчок меняет её состояние; располагается ниже лица; data items 2–4 of {label ≤ 24, on true|false, icon? phone|briefcase|user|clock|chat|star}, clicks? 0–6 of {item number, quote? inner quote}, style? switch|check, size? small|medium|large. phone_call (over): входящий вызов на нейтральном телефоне сбоку (справа, если side не задан как left): звонящий, подзаголовок и круглое кольцо аватара, затем вызов принимается в момент answer_at и запускается таймер (или показывается баннер ожидания); в широких кадрах располагается рядом с лицом, в вертикальных — под ним; data caller ≤ 24, subtitle? ≤ 32, avatar? {asset_id} image (обрезается по размеру), answer_at inner quote, side? left|right, size? small|medium|large, banner? ≤ 32, banner_note? ≤ 48, mask_number? true|false. compare (full): полноэкранная карточка формата 3:5 с изображением «до»; в момент reveal_at изображение «после» появляется диагональным движением (если reveal не задан) или стирается слева к центральному разделителю; оба изображения остаются на экране, с необязательными плашками-подписями; data before {asset_id} image (обрезается по размеру), after {asset_id} image (обрезается по размеру), labels? {before? ≤ 20, after? ≤ 20}, reveal_at inner quote, reveal? sweep|wipe, size? small|medium|large. notification (over): уведомление телефона вверху, над лицом: иконка (или первая буква названия приложения), приложение, заголовок и строка текста; оно появляется сверху, остаётся на экране не менее 1.2 s и исчезает до конца своего интервала; каждая карточка стека появляется сверху в момент at, сдвигая предыдущие назад; data app ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, stack? 1–2 of {app? ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, at? inner quote}, size? small|medium|large. progress (over): 2–5 шагов в столбце на карточке; каждый по очереди отмечается галочкой в момент advance_at quote (по одному на шаг, по порядку) или равномерно; располагается ниже лица; data steps 2–5 of ≤ 20, advance_at? 2–5 of inner quote, size? small|medium|large. rating (over): пять звёзд на карточке, которые по очереди заполняются до значения stars (от 1 до 5, с шагом в половину звезды; половина звезды заполняется наполовину), с необязательной подписью под ними; располагается на уровне груди; data stars number, label? ≤ 32, size? small|medium|large. chat_window (full): полноэкранное окно чата: запрос набирается, ответ появляется по одному слову, таблица открывается построчно, затем появляются карточки ответов — каждая в момент at или равномерно; при zoom true кадр приближается и отдаляется в моменты битов; data app? ≤ 24, prompt ≤ 120, replies? 1–3 of {title ≤ 32, body? ≤ 64, at? inner quote}, answer? {text ≤ 150, at? inner quote}, table? {columns 2–3 of ≤ 16, rows 1–4 of {cells 2–3 of ≤ 20, at? inner quote}}, zoom? true|false, size? small|medium|large. video_grid (full): полноэкранная сетка видео из ресурсов аккаунта в виде плиток 9:16: 2x2 (ячейки 1–4, левый столбец приподнят) или 3x1 (ячейки 1–3); если layout не задан, состав ячеек определяется переданными данными; каждая плитка появляется после предыдущей и воспроизводится без звука, над сеткой может быть заголовок; data layout? 2x2|3x1, cell_1 {asset_id} video (обрезается по размеру), cell_2 {asset_id} video (обрезается по размеру), cell_3 {asset_id} video (обрезается по размеру), cell_4? {asset_id} video (обрезается по размеру), title? ≤ 40, size? small|medium|large. word_title (full): полноэкранный анимированный заголовок акцентного цвета: первая запись появляется с первого кадра шаблона, каждая следующая — в момент at quote (обычно это те же слова, что произносятся), либо равномерно; reveal replace (по умолчанию) показывает по одной записи за раз, build добавляет каждую запись к заголовку; data words 1–8 of {text ≤ 16, at? inner quote}, reveal? replace|build, size? small|medium|large. phone_screen (full): полноэкранный телефон, воспроизводящий видео экрана (без звука; если видео не задано — градиент), состояния которого сменяются по очереди в момент at quote или равномерно: lock (затемнённый экран, замок и текст), play (чёткое видео, текст вверху), liked (сердце и текст), counter (плашка внизу экрана), timer (значок у верхнего края), tag (плашка с линией-указателем сбоку экрана); состояния lock, play и liked сменяют друг друга, теги накапливаются, более поздний counter или timer заменяет предыдущий; data screen? {asset_id} video (обрезается по размеру), states 1–6 of {state lock|play|liked|counter|timer|tag, text? ≤ 24, at? inner quote}, size? small|medium|large. terminal (full): полноэкранная тёмная карточка терминала: команда набирается; diff под ней сворачивает удалённые строки del (красные) и раскрывает добавленные строки add (зелёные) в момент diff.at; затем в момент at появляется строка статуса с галочкой; title задаёт название карточки; data title? ≤ 24, command ≤ 100, diff? {lines 2–7 of {text ≤ 36, change? add|del}, at? inner quote}, status ≤ 40, at? inner quote, size? small|medium|large. pointer_chips (over): 1–4 плашки в столбце ниже лица (справа, если side не задан как left); каждая соединена изогнутой линией с точкой target {x,y} в % кадра от его верхнего левого угла; плашки появляются по очереди в момент at quote или равномерно; линии могут пересекать лицо, плашки не должны его закрывать; также поверх insert; data items 1–4 of {target {x,y}, text ≤ 20, at? inner quote}, side? left|right, size? small|medium|large. chart (full): полноэкранная столбчатая или линейная диаграмма с 2–6 подписанными точками на карточке: в момент at каждой точки или равномерно столбец растёт либо линия дорисовывается до неё, а значение увеличивается; суффикс указывается после значения; заголовок располагается сверху; data type bar|line, title? ≤ 40, suffix? ≤ 6, points 2–6 of {label ≤ 12, value number, at? inner quote}, size? small|medium|large. race (full): полноэкранная гонка столбцов с ранжированием: по одному столбцу на имя, самый длинный — сверху; значения первого раунда показываются с начала, затем в момент at каждого следующего раунда или равномерно столбцы меняются до соответствующих значений и переставляются по рангу, а подпись раунда появляется под ними; data title? ≤ 40, suffix? ≤ 6, names 3–6 of ≤ 14, rounds 2–5 of {label? ≤ 10, values 3–6 of number, at? inner quote}, size? small|medium|large. hand_title (full|over): заголовок (до двух строк) выводится штрих за штрихом рукописным шрифтом, затем маркер рисуется по словам заголовка, начиная с mark.word (индекс от 0), на mark.words слов (по умолчанию 1), в момент mark.at или ближе к концу шаблона; over располагается в области субтитров и скрывает их; data text ≤ 40, mark? {word number, words? number, style highlight|underline|circle, at? inner quote}, size? small|medium|large. word_fill (full): полноэкранное огромное слово, буквы которого показывают ваше видео (clip, воспроизводится без звука), а остальная часть кадра заполнена фоном темы; оно увеличивается в течение первых 10 кадров; data word ≤ 10, clip {asset_id} video, size? small|medium|large.
template_theme	optional	Стиль всех шаблонов в запуске: пресет и необязательный акцентный цвет; используется только с templates.
design	optional	ДНК дизайна запуска: templates, финальная карточка и акцент субтитров используют её. Запросите бренд или используйте extract_brand; если не задано, используется сохранённый бренд-кит. Не сочетается с template_theme.
template_sounds	optional	Принимается; схема пока не содержит описания.
scenes	optional	Графика, созданная для этого видео на основе ваших слов, для того, что не отображается шаблонами: каждый элемент рисуется поверх ведущего (over) или на весь кадр (full), пока произносятся соответствующие слова; элемент, расположенный поверх субтитров, скрывает их на время показа. Элемент, не прошедший проверку, исключается и указывается в warnings[]. 25 кредитов за сцену, отдельная строка цитаты; оплата взимается только за сцены, показанные в готовом видео. Требуются script и соответствие критериям long-form на сервере.
motion_style	optional	Допустимый тип: object.
moves	optional	Движения из list_moves, привязанные к вашим словам: каждое в формате { name, anchor: { quote }, cover_words?, placement?, data? }. Каждое отображается так, как указано в list_moves; data принимает перечисленные там поля. Движение, которое нельзя отобразить для указанных слов или в этом видео, указывается в warnings[] и исключается, а не удаляется без предупреждения. Кредиты за него указываются в цитате.
edit_sounds	optional	Допустимые значения: true | false.
music	optional	Фоновая музыка под голосом, созданная для этого видео; выключена, если вы её не запросили. "auto" определяет настроение по сценарию; { mood } задаёт его вашими словами, например "calm lo-fi". 60 кредитов за видео, отдельная строка в цитате; оплата взимается только если видео передаётся с музыкой.
call	optional	Телефонный звонок после цитаты: ведущий слушает, затем замирает, пока звонок воспроизводится как телефонная линия; сначала звучит звонок, а рядом с ведущим показывается телефон во время разговора (вместо этого используется шаблон phone_call, покрывающий звонок). Требуются script, кадр 9:16 и слова после звонка. Замороженный ведущий и звонок добавляют секунды производства, но не секунды ведущего; показанный во время звонка live-avatar тарифицируется отдельно, как указано в list_prices. Соответствие критериям long-form проверяется на сервере.
interview	optional	Интервью: закадровый голос произносит отмеченные слова сценария своим голосом, ведущий произносит остальной текст в кадре и сохраняет неподвижность, пока говорит закадровый голос. Требуются сценарий и допуск к длинному формату на сервере; неподвижные кадры ведущего добавляют секунды производства, а не секунды ведущего.
presenter_gaze	optional	Куда смотрит ведущий во время этих слов, с точки зрения зрителя: в камеру, влево или вправо. Требуется actor_id с таким ракурсом (list_actors); смена направления взгляда считается склейкой.
shots	optional	Живые кадры с актёром на некоторых словах сценария: talking, talking_action (говорит, одновременно действуя) или action (действует, пока слова звучат за кадром). Кадры не могут перекрываться; слова вне них произносятся в обычном дубле ведущего. Требуются кадр 9:16 и допуск к длинному формату на сервере; у каждого типа своя цена в секундах ведущего в list_prices.
product_asset_id	optional	Изображение товара (ast_…), которое показывается в кадрах с товаром.
person	optional	ПОКА НЕ ПОДДЕРЖИВАЕТСЯ: person пока не поддерживается: в этом запросе используется актёр по умолчанию; выберите actor_id из list_actors или передайте изображение, чтобы выбрать другое лицо
actor_id	optional	Сохранённый ID актёра Clipwright из list_actors. Выберите actor_id, image или person; не указывайте их вместе. Если не указаны voice или voice_id, голос выбирается по гендеру актёра. Не указывайте вместе с actor_gender.
presenter_framing	optional	close (по умолчанию), wide (ведущий ниже, над ним больше пространства) или full (от головы до ног). Требуется ракурс актёра с таким названием (list_actors), только 9:16; для full используется wide, затем close, а также добавляются предупреждения[].
presenter_mic	optional	true: ведущий держит крошечный микрофон. Требуется ракурс актёра с микрофоном при таком кадрировании (list_actors; в библиотеке используется wide); иначе микрофона не будет и добавятся предупреждения[].
image	optional	Общедоступный URL изображения актёра по протоколу https (PNG, JPEG или WebP, до 10 МБ). Файл на диске сначала нужно передать через upload_image (POST /v1/uploads) — укажите возвращённый URL. Источник, который нельзя использовать, — закрытый или локальный хост, http, недоступный, перенаправляющий, размером более 10 МБ или не одного из этих типов изображений — отклоняется (unusable_source) до списания средств. Гендер лица не определяется: укажите actor_gender или voice, иначе будет использован мужской голос по умолчанию с предупреждением.
actor_gender	optional	Гендер лица на image: female | male. Только вместе с image: выбирает голос по умолчанию для этого гендера (female: sarah, male: george; для gemini-3.8-flash-tts: kore и charon). Отклоняется вместе с actor_id (его гендер известен) и без image. Явно указанные voice или voice_id имеют приоритет, а в ответе будет предупреждение, что actor_gender ничего не изменил.
name	optional	ПОКА НЕ ПОДДЕРЖИВАЕТСЯ: name пока не поддерживается: параметр не передаётся рендереру
broll_policy	optional	Политика для B-roll: anyone разрешает людей, включая актёра; no_actor исключает актёра; no_people исключает всех людей, включая руки. Для шаблонов с вашим изображением или видео требуется "anyone"; в противном случае значение только сохраняется. Переопределение в запуске имеет приоритет над настройкой актёра по умолчанию для аккаунта; иначе используется no_people.
captions	optional	Встроить в видео субтитры с синхронизацией по словам, поверх ведущего и вставок. Недоступно с segments.
caption_style	optional	Внешний вид субтитров при captions=true. hormozi: стиль по умолчанию: жирные белые заглавные буквы с толстой чёрной обводкой, до трёх слов в подсказке, одно ключевое слово в каждой подсказке жёлтым (выделенное, иначе самое длинное слово, не являющееся стоп-словом). accent: узкие жирные белые заглавные буквы без обводки, до трёх слов в подсказке, одно ключевое слово в каждой подсказке оранжевым (выделенное, иначе самое длинное слово, не являющееся стоп-словом). tiktok: жирные округлые заглавные буквы, по одному или два слова за раз; произносимое слово становится жёлтым и увеличивается. youtube: чёткий жирный шрифт без засечек, четыре слова (пять в 16:9) на тёмной скруглённой плашке внизу; слова появляются с затуханием, произносимое слово — красным. instagram: комические заглавные буквы с розовой обводкой, по два слова за раз; произносимое слово появляется оранжевым. minimalist: простой шрифт без засечек, четыре слова на полупрозрачной тёмной полосе, плавное появление. neon: голубые заглавные буквы с пурпурной обводкой, по два слова за раз; произносимое слово появляется белым. genz: крупные комические заглавные буквы, по одному слову за раз, резко появляются с розовой подсветкой. campfire: округлые комические заглавные буквы, три слова; произносимые слова загораются золотым и остаются подсвеченными. midnight: жуткие заглавные буквы, два слова, медленное появление; произносимое слово — красным. plottwist: жирный шрифт без засечек, три слова; произносимое слово становится небесно-голубым и увеличивается. headline: высокие узкие заглавные буквы на сплошной чёрной полосе, три слова; произносимое слово увеличивается и становится жёлтым. promo: жирный шрифт без засечек на синей плашке-капсуле, три слова; произносимое слово появляется жёлтым. lecture: удобный для чтения шрифт без засечек, четыре слова на тёмной скруглённой плашке; произносимое слово становится зелёным. highlighter: жирный шрифт без засечек, четыре слова; произносимые слова становятся лаймовыми и остаются подсвеченными. studio: шрифт без засечек, четыре слова печатаются на размытой тёмной плашке; произносимое слово — янтарным. broadcast: шрифт без засечек с обводкой, четыре слова в нижней части кадра; произносимое слово — бледно-жёлтым. arcade: угловатые жёлтые заглавные буквы, два слова; произносимое слово подпрыгивает и становится белым. clutch: заглавные буквы, имитирующие мазок кисти, по одному слову за раз, резко появляются зелёными. bubblegum: округлые декоративные буквы с розовой обводкой, два слова; произносимое слово подпрыгивает и становится жёлтым. crayon: рукописные буквы, имитирующие маркер, с тёмно-синей обводкой, два слова; произносимое слово появляется оранжевым. lyrics: рукописный шрифт, четыре слова; произносимые слова загораются розовым и остаются подсвеченными. bassdrop: декоративные заглавные буквы с обводкой, по одному слову за раз, увеличиваются и становятся оранжевыми. punch: подводка и кульминация в середине кадра: небольшая белая строка-подводка над одним или двумя крупными светящимися синими ключевыми словами; остальные слова мелкие и белые. Псевдоним: minimal соответствует minimalist. Если шрифт не поддерживает буквы сценария, он заменяется простым шрифтом без засечек. Предпросмотры: https://clipwright.io/captions
caption_emphasis	optional	Ключевые слова или короткие фразы для выделения; каждая цитируется из script и сопоставляется так же, как цитата для вставки (регистр и пунктуация не учитываются). Элемент — это цитата или { quote, look }: look punch показывает небольшую строку-подводку из того же предложения над цитатой в виде крупного светящегося ключевого слова, look pill показывает только цитату в скруглённой плашке-капсуле, look color показывает её акцентным цветом того же размера, look box показывает её на мягкой плашке акцентного цвета того же размера. Если look не указан, punch использует стиль punch, hormozi и accent используют color, а остальные пресеты показывают цитату крупнее, цветом подсветки. Выделяются все вхождения. Требуются captions=true и script; если цитаты нет в script, запрос отклоняется до списания средств.
caption_mode	optional	full (по умолчанию, если не указано): субтитры показывают каждое произнесённое слово. highlights: субтитры появляются только вокруг цитат из caption_emphasis (подводка, цитата, короткое продолжение) и больше нигде; требуется caption_emphasis. В обоих режимах субтитры скрываются, пока на экране находится полноэкранная вставка или шаблон пересекается с их полосой.
caption_position	optional	Расположение субтитров: top, middle, lower или bottom (80% высоты). Если не указано, используется положение, заданное в caption_style. Требуется captions=true.
caption_place	optional	Вместо caption_position задаёт высоту субтитров; наложения не перемещают их, а наложение, пересекающееся с ними, отклоняется, если оно не размещено относительно relative_to captions. Требуется captions=true.
presenter_place	optional	Высота и центр лица ведущего в кадре. Портрет кадрируется плотнее, чтобы достичь нужного положения; если ракурс close слишком тесный, используется широкий ракурс актёра; если и он слишком тесный, в warnings[] указывается высота лица в кадре. Требуются actor_id и script с overlays, inserts, layout_windows, framing или call. Цена не меняется.
look	optional	ПОКА НЕ ПОДДЕРЖИВАЕТСЯ: look пока не поддерживается: параметр не передаётся рендереру
aspect_ratio	optional	Формат вывода: 9:16 | 1:1 | 16:9. Если не указано и image отсутствует, используется 9:16; если image указан, используется поддерживаемый формат, наиболее близкий к пропорциям изображения, даже если оно альбомное — указывайте формат явно при каждом использовании image. Несоответствие между запросом и источником более чем на 15% отклоняется (aspect_conflict) до списания средств.
resolution	optional	Разрешение вывода: 720p | 1080p (короткая сторона — 720 / 1080 px). Если не указано, используется 1080p.
voice	optional	Название голоса из list_voices. Подобранные пресеты: sarah | george | eric | daria_ru_female. API отклоняет название, которого нет в ответе list_voices, до списания средств. Если не указано, используется голос по умолчанию для гендера актёра: гендер actor_id, actor_gender при наличии image или george для актёра по умолчанию и для image без actor_gender. gemini-3.8-flash-tts поддерживает только собственные голоса (kind model_voice в list_voices, например kore): указание такого голоса выбирает эту модель, а голос отклоняется, если tts_model его не поддерживает, до списания средств. Несовместимо с voice_id.
voice_id	optional	Необработанный ID голоса поставщика (16–32 буквы и цифры) для голоса вне каталога. Проверяется отложенно: неизвестный ID приводит к ошибке запуска, а не запроса. Отклоняется вместе с tts_model=gemini-3.8-flash-tts. Несовместимо с voice.
tts_model	optional	Модель синтеза речи: eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5 | eleven_v4 | gemini-3.8-flash-tts. Если не указано, используется модель выбранного голоса (её показывает list_voices): gemini-3.8-flash-tts для её собственных голосов, eleven_v4 для всех пресетов, голосов из каталога и необработанного voice_id. Явно указанная tts_model имеет приоритет, кроме eleven_v3: эта модель больше не используется для озвучивания, и запуск с ней выполняется на eleven_v4 с предупреждением. eleven_v4 и gemini-3.8-flash-tts учитывают знаки ударения (заглавная гласная внутри русского слова, например "потОм", становится ударной; см. script); eleven_flash_v2_5 и eleven_turbo_v2_5 — более дешёвые альтернативы для языков, отличных от русского. gemini-3.8-flash-tts поддерживает только собственные голоса (list_voices с model=gemini-3.8-flash-tts; если voice не указан, kore для актёра женского гендера и charon в остальных случаях) и не возвращает тайминги слов: пресет или голос из каталога, voice_id, captions=true, segments и inserts с этой моделью отклоняются до списания средств. Аудиотеги в квадратных скобках — соглашение для других моделей синтеза речи; эта модель их не измеряет. Ограничения длины сценария для моделей синтеза речи: eleven_v3: 5000 символов; eleven_flash_v2_5: 10000 символов; eleven_turbo_v2_5: 10000 символов; eleven_v4: 5000 символов; gemini-3.8-flash-tts: 5000 символов. В подсчёт входят пробелы, аудиотеги и знаки ударения; эмодзи могут считаться за два символа. Теги пауз удаляются из текста, отправляемого в eleven_v4 и gemini-3.8-flash-tts, и не учитываются при подсчёте для этих моделей. Ограничения на количество слов нет. Длительность и цена остаются приблизительными до измерения.
voice_pace	optional	Скорость повествования; 1 — естественная скорость голоса. Для gemini-3.8-flash-tts вместо этого задаётся подсказка стиля; у eleven_v4 нет настройки скорости, поэтому выбирайте голос по значению words_per_second из list_voices; оба случая указываются в warnings[].
pause_trim	optional	Обрезать паузы длиннее указанного количества секунд; false сохраняет все паузы. Значения по умолчанию для шаблонов, сцен и shots: 0.15 для предложения, 0.08 для запятой.
end_hold_s	optional	Сколько секунд последний кадр остаётся на экране после последнего слова: ведущий замирает, и все слои на экране остаются неподвижными. Секунды производства, а не секунды ведущего. Требуются script и допуск к длинному формату.
visible_ai_label	optional	Видимая метка ИИ для новых видео с ведущим, включая длинный формат; по умолчанию включена политикой допуска на сервере. Значение false скрывает только видимую метку и не отключает невидимую маркировку или подписанное подтверждение происхождения. Исторические результаты не меняются.
background	optional	Допустимые значения: white | blur | contain.
create_actor. Создаёт персонального актёра для этой учётной записи по словам, описывающим вымышленного взрослого: портрет 9:16 ровно с одним лицом, а также другие запрошенные форматы, отредактированные на его основе. Сразу возвращает run_id; опрашивайте get_run, пока статус не станет 'succeeded' (created_actor.actor_id, затем передайте его как actor_id в make_ugc) или 'failed'. За каждое опубликованное изображение взимается цена, указанная в предложении; за отклонённые описания и непригодные портреты плата не взимается. Если генерация отключена, вызов завершается ошибкой actor_generation_disabled. from_actor_id сохраняет лицо (это проверяется; при несовпадении плата не взимается). Если указан style_reference, портрет, похожий на человека на фотографии, отклоняется без оплаты, цена при этом не меняется. portrait (с gender и approximate_age) становится портретом 9:16 без оплаты; оплачиваются только другие форматы. Изображение не с ровно одним лицом или с лицом, обрезанным, слишком маленьким или слишком большим, отклоняется без оплаты. Маскот бренда, нарисованный с помощью generate_image, может стать таким портретом, если его лицо воспринимается как человеческое (мультяшный человек); маскот-животное или маскот-предмет будет отклонён, поэтому показывайте его во вставках.

Field	Required	What it means
description	optional	Слова, описывающие вымышленного взрослого: внешность, одежда, обстановка. Упоминание реального человека или сходства с ним отклоняется до списания средств (actor_prompt_refused). Обязательно, если не указаны from_actor_id или portrait; при from_actor_id задаёт внешний вид, одежду и позу в кадре, а пол и возраст остаются такими же, как у исходного актёра.
gender	optional	female | male. Задаёт пол актёра и голос по умолчанию для видео с этим актёром. Обязательно, если не указан from_actor_id.
approximate_age	optional	Примерный возраст в годах: от 18 до 90; актёры — взрослые. Обязательно, если не указан from_actor_id.
name	required	Имя, отображаемое в list_actors.
aspect_ratios	optional	Форматы для создания: 9:16 | 1:1 | 16:9; формат 9:16 включается всегда. Если не указано, создаются все три. За форматы, не прошедшие проверку идентичности, плата не взимается; они перечисляются в warnings.
from_actor_id	optional	Создать нового персонального актёра на основе этого актёра (из библиотеки или вашего): то же лицо, пол и возраст, но другой ракурс за счёт кадрирования, предметов в руках, обстановки, description или style_reference. Не указывайте gender и approximate_age.
framing	optional	Размер плана: close (по умолчанию, по грудь), wide (по пояс, руки видны, над головой есть пространство) или full (в полный рост, от головы до ног). При создании по словам задаёт кадрирование нового портрета; с from_actor_id варианты wide и full отодвигают камеру. Ракурс определяется по размеру лица на изображении, а make_ugc использует для его рендеринга presenter_framing с таким же названием. Не используется с style_reference или portrait, поскольку кадр задаётся изображением.
holding	optional	До 2 предметов, которые держит ведущий: по одному в каждой руке.
setting	optional	Описанная словами комната или фон, где будет находиться ведущий.
style_reference	optional	Фотография в формате PNG или JPEG, по которой новый портрет повторяет обстановку, освещение, угол камеры, размер плана и одежду: по грудь, по пояс или в полный рост, как на фотографии; портрет шире, чем по грудь, становится ракурсом wide. Изображение — это ресурс этой учётной записи (загрузка, импорт по URL или найденное изображение, rights_confirmed). Без from_actor_id лицо создаётся заново по description; с ним используется лицо исходного актёра. Портрет, похожий на человека на фотографии, отклоняется без оплаты.
portrait	optional	Создать актёра на основе собственного портретного изображения, а не генерировать его: изображение PNG или JPEG, являющееся ресурсом этой учётной записи (rights_confirmed), с соотношением сторон в пределах 2% от 9:16 и ровно одним лицом, которое не обрезано и не слишком маленькое или большое. Оно становится портретом актёра 9:16 без оплаты; другие форматы редактируются на его основе и оплачиваются как обычно. Укажите gender и approximate_age; нельзя использовать вместе с description, style_reference или from_actor_id.
quality	optional	Качество изображения: medium | high. Если не указано, используется medium. high создаёт наиболее естественный портрет. Цена за изображение зависит от этого параметра; она указана в предложении до списания средств.

make_faceless. Создаёт готовое платное видео без ведущего на основе сценария или краткого описания. Выберите длительность от 30 до 90 секунд; видео заканчивается вместе с озвучкой, длится не менее 25 секунд (для объясняющего видео — столько же, сколько озвучка) и не более чем на четверть дольше выбранной длительности, но никогда не превышает 90 секунд. Видео состоит из вступительного анимированного клипа и сцен с изображениями. Субтитры включены по умолчанию, их можно отключить.

Сразу возвращает run_id; опрашивайте get_run с его poll.arguments, пока статус не станет 'succeeded' (video_url) или 'failed'. attempt=2,3,… запускает НОВЫЙ процесс для тех же входных данных.

Field	Required	What it means
input_mode	required	'script' озвучивает ваш текст без изменений; 'brief' создаёт текст озвучки по краткому описанию. Передайте ровно одно из полей script или brief, соответствующее этому режиму.
script	optional	Текст озвучки, который читается без изменений. Обязателен, если input_mode — 'script'; должен отсутствовать, если input_mode — 'brief'.
brief	optional	Тема видео; по ней создаётся текст озвучки. Обязателен, если input_mode — 'brief'; должен отсутствовать, если input_mode — 'script'.
duration_seconds	required	Выбранная длительность от 30 до 90 секунд, кратная кадру 1/25 с. Видео заканчивается вместе с озвучкой и длится не менее 25 секунд (для объясняющего видео — столько же, сколько озвучка), обычно не более чем на четверть дольше выбранной длительности и не более 90 секунд; если озвучка длиннее, видео длится до её окончания. Если видео длиннее выбранной длительности более чем на 5 секунд, это указывается в warnings[]. Сумма списания никогда не превышает указанную в предложении. Сценарий принимается, если его расчётная длительность составляет от 21 секунды до выбранной длительности плюс 5 секунд, но не более 90 секунд.
style_reference	optional	Общедоступное изображение по https, визуальный стиль которого используется в сценах.
character_reference	optional	Общедоступное изображение человека или персонажа по https, внешний вид которого сохраняется во всех сценах.
character_details	optional	Неизменные визуальные особенности этого человека или персонажа, например причёска, одежда и отсутствие аксессуаров; сохраняются в каждой сгенерированной сцене.
scene_images	optional	Ваши изображения, каждое из которых размещается в диапазоне слов или рядом с цитатой из озвучки.
captions	optional	Встроенные в видео субтитры; включены по умолчанию.
transitions	optional	Вспышка или засветка на склейках со звуком: при каждой смене сцены либо у ближайшей к каждой опорной фразе склейки (только для script). Если не указано для brief, вспышка добавляется при каждой смене сцены; false означает обычные склейки. Дополнительная плата не взимается.
edit_sounds	optional	Тихий звук при каждой смене сцены, с пиком на склейке; для него используется template_sounds.edit. Цена не меняется.
template_sounds	optional	false — без звуков; либо { flash, whoosh (light leak), edit: name } из list_template_sounds.
music	optional	Фоновая музыка под голосом, созданная для этого видео; по умолчанию выключена. "auto" выбирает настроение по сценарию; { mood } задаёт его вашими словами, например "calm lo-fi". 60 кредитов за видео; отдельная строка в предложении, списание только при доставке видео с музыкой.
templates	optional	Только для script: как в make_ugc, слот может показывать ваше изображение или видео (asset_id, rights_confirmed). Бесплатно.
shots	optional	Только для script: 1–10 объектов {id, anchor, action, asset_id?}, максимум по 5 с каждый.
scenes	optional	Только для script: как сцены make_ugc.
motion_style	optional	Как motion_style в make_ugc; применяется только к script. Бесплатно.
moves	optional	Только для script: движения из list_moves по вашим словам: каждый объект имеет вид { name, anchor: { quote }, cover_words?, placement?, data? }. Каждое движение отрисовывается так, как описано в его строке list_moves; data содержит указанные там поля. Движение, которое нельзя отрисовать для заданных слов или в этом видео, указывается в warnings[] и пропускается, а не удаляется без предупреждения. Кредиты за него указаны в предложении.
format	optional	'explainer': рисованный объясняющий мультфильм, действие для каждого слова, персонаж в углу; только для script. Подходит для последовательности конкретных действий, описанных одним рассказчиком: пошаговой инструкции, объяснения принципа работы, рабочего процесса, обзора инструмента, N ошибок или N способов, когда для каждой фразы есть что показать. Рассуждения без действий, диалоги и истории о людях подходят плохо. В каждом предложении для сценария указывается explainer_fit: предлагайте этот формат, если он подходит; если нет — укажите причину и предложите переписать сценарий в виде действий, прежде чем спрашивать. Персонаж создаётся по character_reference или character_details (его поза отображается в предложении); если они не заданы, используется наш персонаж, бесплатно. Для списка названных предметов в сцене показывается изображение каждого из них, по одному на предмет из предложения; плата взимается только за показанные изображения. Если голос не указан, английский сценарий озвучивается нашим самым быстрым голосом.
pause_trim	optional	Только для script: как pause_trim в make_ugc; то же значение по умолчанию, что и для templates, scenes, shots или format explainer.
voice	optional	Голос озвучки: имя из list_voices с skill=make_faceless (kind faceless_voice). Если не указано, используется narrator_en_wise_lady; для английского объясняющего видео — самый быстрый голос. Выберите голос на языке озвучки: любой голос может читать на любом языке, но с собственным акцентом. API отклоняет неизвестное имя и голос make_ugc до списания средств. Необработанный voice_id здесь не принимается.

• В видео make_faceless нет ведущего в кадре: озвучка звучит поверх вступительного анимированного клипа и сцен с изображениями. Передайте ровно одно из полей script и brief — то, которое указано в input_mode.
• duration_seconds — это целевая длительность, а не длительность, до которой растягивается видео: видео заканчивается вместе с озвучкой, которая длится не менее 25 секунд (для объясняющего видео — ровно столько, сколько сама озвучка) и обычно не более чем на четверть дольше duration_seconds, но не более 90 секунд; более длинная озвучка звучит до конца. Если видео длиннее более чем на 5 секунд, это указывается в warnings[]. Сумма списания никогда не превышает указанную в предложении.
• Субтитры не содержат знаков препинания, сохраняют акценты и другие диакритические знаки, а числа отображаются в исходном виде. Если субтитры включены, сценарий проверяется на совместимость со шрифтом до создания речи; если шрифт не может отобразить какой-либо символ, процесс завершается ошибкой без списания средств.
• Язык озвучки определяется автоматически.
• Параметр voice задаёт голос озвучки: выберите имя из GET /v1/voices?skill=make_faceless. Если он не указан, озвучка выполняется голосом narrator_en_wise_lady, а английское объясняющее видео — самым быстрым голосом. Выберите голос на языке озвучки. Неизвестное имя, голос make_ugc и voice_id отклоняются до списания средств: make_faceless использует только голоса, перечисленные для него.
• make_faceless всегда создаёт видео в формате 1080p и соотношении сторон 9:16. Если генерация видео без ведущего отключена на сервере, оба его вызова возвращают paid_render_disabled, и плата не взимается.
• Если ошибка неудачного процесса начинается с story_not_planned, он остановился на первом шаге: в этой попытке не удалось спланировать озвучку. Плата не взимается; те же входные данные можно запустить снова с новым Idempotency-Key.

Для make_ugc и create_actor формат результата зависит от запроса и исходного материала. Поддерживаются форматы 9:16, 1:1, 16:9 и разрешения 720p, 1080p; если ничего не указано, используется 1080p и 9:16.

08

Рабочие процессы

GET /v1/public/workflows перечисляет методы, которые можно запустить. Встроенные методы: ugc-product-intro, ugc-faq-answer, faceless-explainer и product-image-story. website-proof-demo и kinetic-launch пока недоступны для запуска и остаются в состоянии execution_blocked с указанием причин.

Самый короткий путь с CLI начинается с собственного примера метода. Кредиты расходуются только при выполнении plan-run; все команды до него бесплатны. Отредактируйте brief до создания плана и сохраните закреплённые параметры метода.

clipwright workflow-show faceless-explainer > method.json
jq '{document: {v: 1, method: {method_id: .descriptor.id, version: .descriptor.version, content_digest: .descriptor.content_digest, capability_digest: .capabilities.content_digest}, brief: .descriptor.example.brief, beats: .descriptor.example.beats, claims: [], assets: []}}' method.json > create.json
clipwright plan-create --file create.json > plan.json
jq '{revision, content_digest}' plan.json > approval.json
clipwright plan-approve wfp_example --file approval.json
clipwright plan-quote wfp_example > quote.json
jq '{revision, content_digest, semantic_input_digest, quote_id, idempotency_key: "workflow-example:1"}' quote.json > launch.json
clipwright plan-run wfp_example --file launch.json
clipwright runs run_example

Замените wfp_example на plan_id из plan.json, а run_example — на идентификатор запуска, который выводит plan-run. Срок действия предложения истекает через пять минут после его выдачи, поэтому запускайте plan-run вскоре после plan-quote. Для product-image-story загрузите каждую фотографию с помощью clipwright upload --json. В ответе будут указаны её upload_id и content_digest; скопируйте их непосредственно в ресурс. Добавьте по одному ресурсу на каждую фотографию. Команда uploads возвращает те же идентификаторы для ранее загруженного файла.

clipwright upload mug-front.jpg --json > upload.json
jq '{instance_id: "mug-front", asset_id: .upload_id, content_digest, anchor: {quote: "overall shape"}, provenance: "owner_supplied", rights: "owner_authorized", purpose: "product_proof"}' upload.json > asset.json

{
  "instance_id": "mug-front",
  "asset_id": "upl_00000000000000000000000000000000",
  "content_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "anchor": {
    "quote": "overall shape"
  },
  "provenance": "owner_supplied",
  "rights": "owner_authorized",
  "purpose": "product_proof"
}

• Создайте план, принадлежащий аккаунту, сохраните его редакции и одобрите точную редакцию и content_digest. Планирование и одобрение ничего не стоят и не запускают рендеринг. Для отредактированной редакции требуется новое одобрение.
• Для одобренного плана отправьте POST с пустым телом на /v1/workflow-plans/{id}/quote. Используйте его quote_id, revision, content_digest и semantic_input_digest в запросе на запуск. Перед началом новой покупки проверьте expires_at; это метаданные предложения. Idempotency-Key должен совпадать со значением idempotency_key в теле запроса.
• В предложениях для рабочих процессов UGC в native_quote.quote.warnings указано, что duration_estimate_sec и credits_estimate — это оценки, а не фиксированная цена. За готовое короткое видео UGC взимается плата согласно его price_lines, рассчитанным по измеренной длительности видео с округлением каждой строки вверх до целых секунд. Поэтому за видео длиннее расчетного будет взиматься больше, чем указано в оценке. Прочитайте credits_charged в завершенном запуске. В нативном предложении с long_form_pricing вместо этого используются проверенные интервалы присутствия лица в готовом видео и тариф, зафиксированный при допуске, а не общая длительность видео. При этом продолжают действовать нативные условия для сбоев.
• Нативный тариф и правила для сбоев продолжают действовать. Faceless duration_seconds задает длительность, по которой предложение ограничивает сумму списания; измеренная длительность озвучивания определяет длительность готового видео. Для голоса, субтитров и точного принятого сценария сохраняются нативные настройки.
• Свяжите каждое предоставленное изображение с отдельным instance_id, стабильным asset_id загруженного вами файла, content_digest, правами, происхождением, назначением и непересекающимся диапазоном слов или однозначной цитатой. Используйте одну загрузку в нескольких экземплярах; временные подписанные URL разрешаются при расчете предложения и запуске.
• Исходные изображения продукта размещаются в поддерживаемых кадрах IMAGE. Сгенерированное вступление носит иллюстративный характер. Точное слайд-шоу только из статичных изображений, вступление только с клиентом и произвольные макеты сцен недоступны, если они обязательны.
• protected_area — это прямоугольник в долях исходного изображения. Предварительная проверка должна сохранять его при кадрировании, движении PAN и добавлении субтитров. Изображения с неподтвержденной ориентацией или размещением отклоняются; сгенерированное изображение не заменяет обязательное исходное подтверждение.
• Защищенные PNG с анимацией или блоками EXIF и JPEG с любым сегментом APP1 (EXIF/XMP) отклоняются. Экспортируйте статичную копию с правильной ориентацией и без этих метаданных. Для проверки покрытия используется нативная шкала кадров с частотой 25 fps.
• Срок хранения загрузки и 24-часовой срок действия подписанного URL — независимые ограничения; предложение не продлевает ни один из них. Исходные файлы и подписи должны оставаться доступными для рендеринга и восстановления. При принятом повторном запросе сохраняются исходные файлы и подписи.
• Успешный запуск возвращает квитанцию и существующий нативный Run. Повторите тот же принятый запрос, чтобы получить эту покупку, в том числе после истечения срока действия предложения или утраты доступности подписи источника. Получите сведения о ходе выполнения и готовое видео через GET /v1/runs/{id}.
• Приватные планы принадлежат аккаунту, которому принадлежит токен.
• Для product-image-story сгенерированные сцены и изображение вступления используют первые два различных подходящих исходных изображения из product_proof в порядке принятых ресурсов. Первое задает форму продукта, второе показывает его с другого ракурса. Готовность плана и нативное предложение сообщают выбранное количество и предупреждают, что сгенерированные иллюстрации могут отличаться. Дополнительные исходные изображения сохраняют точные привязанные к ним места размещения. При восстановлении более ранней оплаченной контрольной точки используются существующие сцены с явным предупреждением, если невозможно проверить обусловленность исходным изображением продукта. Редакции и варианты, включая сохраненные варианты и последующие редакции, сохраняют это известное ограничение обусловленности и не гарантируют, что старые сцены или места размещения сохранятся после редактирования.
• При записи отклоняются неизвестные поля и документы размером более 256000 байт JSON. При чтении принимаются будущие поля и значения перечислений; неизвестные поля в прочитанном документе сохраняются, поэтому старый клиент отклонит неподдерживаемое сохранение, а не удалит намерение. Не изменяйте принятый исходный текст озвучивания.
• Если ответ на сохранение потерян, повторите тот же запрос с явными base_version и document. Если документ уже стал текущим, сервер вернет эту редакцию, не сбрасывая одобрение; если текущий документ отличается, будет возвращен workflow_conflict. SDK, MCP и CLI не одобряют, не рассчитывают предложение и не покупают ничего в качестве побочного эффекта сохранения.
• GET /v1/runs/{id} может содержать workflow: неизменяемую квитанцию, approved_plan, нативное состояние и предупреждения, actual_output, asset_placements, рекомендательные beat_dispositions, validation_issues и creative_acceptance=not_reviewed. В approved_plan не включается brief.reference_profile, поэтому при опросе он не повторяется; сведения о том, что план не воспроизводит из эталона, содержатся в предупреждениях, а GET /v1/workflow-plans/{id} возвращает полную текущую редакцию. Запуск сохраняет приобретенную редакцию, даже если черновик изменится. Редакция или вариант кадра не наследует квитанцию своего предка.
• При проверенном расчете для faceless предоставляются дайджест артефакта, формат и измеренная длительность, даже если позднее отсутствуют необязательные геометрические данные. Для мест размещения требуется неповрежденная контрольная точка, привязанная к аккаунту, запуску и запросу; при отсутствии подтверждения возвращается null с проблемой проверки. Проверенный пустой список мест размещения — []. Для готового UGC предоставляются измеренные формат, длительность и дайджест итогового файла; формат определяется по измеренным размерам, а не по запросу. Для UGC без подтверждения байтов/формата, включая более старые запуски, возвращается actual_output=null с output_evidence_unavailable; результатом остается его нативный video_url. Исторические подтверждения не продлевают срок действия истекшей ссылки на скачивание и не подтверждают человеческую творческую приемку.
• Методы SDK: listWorkflows, getWorkflow, createWorkflowPlan, planReferenceRemake, getWorkflowPlan, saveWorkflowPlan, approveWorkflowPlan, quoteWorkflowPlan и runWorkflowPlan; getRun сохраняет свидетельства рабочего процесса. Команды CLI: workflows, workflow-show, plan-create --file, plan-show, plan-save --file, plan-approve --file, plan-quote и plan-run --file. Эти команды рабочего процесса выводят JSON; перед разбором размер файлов ограничивается 1 MiB. Файл plan-show можно отредактировать и передать в plan-save для того же плана.

Пример тела запроса для POST /v1/workflow-plans/{id}/run: замените поля предложения данными предложения одобренного плана и отправьте Idempotency-Key: workflow-example:1.

{
  "quote_id": "wq_example",
  "revision": 1,
  "content_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "semantic_input_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "idempotency_key": "workflow-example:1"
}

09

Запуск

Платный вызов требует один заголовок помимо ключа: Idempotency-Key. Для POST /v1/skills/make_faceless/run, POST /v1/runs/{id}/revisions, POST /v1/runs/{id}/candidates, POST /v1/skills/make_ugc/run, POST /v1/skills/create_actor/run, POST /v1/workflow-plans/{id}/run, POST /v1/skills/generate_image/run, POST /v1/skills/generate_video/run, POST /v1/reference-analyses, POST /v1/creator-profiles и POST /v1/trend-searches он обязателен. Вызов без него отклоняется с ошибкой 400 idempotency_key_required до списания средств.

• Вы выбираете ключ; только он позволяет отличить повтор запроса от второго заказа. Подойдет любая уникальная строка; сохраняйте ее, пока можете повторно отправить вызов.
• Повторный запрос с тем же ключом и тем же телом возвращает уже запущенный Run и не списывает средства повторно. Благодаря этому обычный повтор безопасен.
• Запрос с тем же ключом, но другим телом отклоняется с ошибкой 409 idempotency_key_reused. Для нового запроса используйте новый ключ, а не изменяйте запрос, ключ которого уже использован.
• Чтобы намеренно запустить новый Run с теми же входными данными — повторить запуск после сбоя, — отправьте новый ключ. Уже оплаченный Run останется без изменений.
• @clipwright/sdk и @clipwright/mcp-server формируют ключ за вас на основе клиента и входных данных, а attempt=2, 3 … превращают в новый ключ. При работе через обычный HTTP ключ выбираете вы.

10

Если вызов завершился ошибкой

Каждый отказ содержит объект ошибки с кодом и сообщением. Дальнейшие действия зависят от типа отказа, а не от текста сообщения:

Отказ	HTTP	Повторить тот же вызов?	Что делать	Списано
rate_limited	429	да, после ожидания	Это ограничение нагрузки, а не ошибка: в ответе указано, сколько секунд ждать, в заголовке Retry-After и в теле.	Ничего. Вызов не был принят.
server_error	500, 502, 503	да, после ожидания	Сбой произошел на стороне сервера. Не запускайте второй Run с новым ключом идемпотентности: повторите тот же вызов.	Не в результате этого ответа. Возвратится удержание кредитов за Run, который сервер не смог запустить; запущенный Run оплачивается один раз в соответствии с его результатом.
insufficient_credits	402	нет, ответ будет тем же	Остановитесь и сообщите человеку о балансе и цене; оба значения указаны в теле ответа. Повтор запроса не изменит ни то, ни другое.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
debt_outstanding	402	нет, ответ будет тем же	Остановитесь. Покупка кредитов сначала погашает долг, и только затем средства поступают на баланс, снимая блокировку.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
not_admitted	403	нет, ответ будет тем же	Остановитесь. У аккаунта нет доступа к бета-версии; ни повтор запроса, ни покупка этого не изменят. Обратитесь в службу поддержки.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
edit_conflict	409	нет, ответ будет тем же	Остановитесь. Черновик редактирования имеет другую версию, чем та, на основе которой было выполнено сохранение; она указана в теле ответа. Прочитайте черновик: если в нем уже есть ваш документ, предыдущее сохранение прошло успешно. В противном случае примените изменение к прочитанному документу и сохраните его с указанной версией.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
run_not_editable	409	нет, ответ будет тем же	Остановитесь. У Run нет черновика редактирования, который можно прочитать или сохранить. Состояние и причина указаны в теле ответа и совпадают с данными о состоянии кадров Run.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
editing_closed	503	нет, ответ будет тем же	Остановитесь. Платное редактирование недоступно; причина указана в теле ответа. Средства не списаны и Run не создан; поле paid_edits в данных о кадрах Run указывает, когда редактирование станет доступно.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
edit_ceiling_reached	409	нет, ответ будет тем же	Остановитесь. Для исходного Run достигнут лимит редакций или вариантов кадров (они учитываются отдельно), которые могут выполняться, завершиться с ошибкой или остаться незавершенными; в теле ответа указаны лимит, количество и Run. Отслеживайте выполняющийся Run через GET /v1/runs/{id} и запускайте следующий после его завершения; служба поддержки увеличит лимит редакций после сбоя, произошедшего по нашей вине.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
edit_invalid	422	нет, ответ будет тем же	Остановитесь. Документ или операция, запрошенная вариантом кадра, нарушает правила Run, который редактируется; в issues перечислены все проблемы по порядку. Исправьте запрос: правила указаны в данных о кадрах Run.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
workflow_invalid	400	нет, ответ будет тем же	Остановитесь. Прочитайте все проблемы и предупреждения, затем исправьте документ рабочего процесса. Одобрение, расчет предложения и платный запуск — отдельные явные вызовы.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
workflow_conflict	409	нет, ответ будет тем же	Остановитесь. Прочитайте сохраненный план и сравните его редакцию и документ с исходным запросом. Если результат запуска неизвестен, восстановите его с исходным запросом и ключом идемпотентности; новый ключ может привести к двойной оплате.	За этот вызов ничего. Запуск, выполненный ранее, оплачивается один раз в соответствии с его результатом; исходный запрос и ключ вернут его.
workflow_not_ready	409	нет, ответ будет тем же	Остановитесь. Прочитайте все проблемы и предупреждения. Устраните причины неготовности, затем явно одобрите и рассчитайте предложение для выбранной редакции перед платным запуском с ключом идемпотентности.	Ничего. Вызов отклонен до создания Run или удержания кредитов.
client_error	400, 401, 403, 404, 409, 410, 413, 415, 422, 503	нет, ответ будет тем же	Остановитесь. Сам запрос был отклонен: прочитайте сообщение, исправьте вызов и отправьте его снова.	За этот вызов ничего: Run не создан и кредиты не удержаны. Run, ранее запущенный с тем же Idempotency-Key (409 idempotency_key_reused), оплачивается один раз в соответствии с его результатом.
Это все коды, которые API помещает в error.code. Код, который вы видите впервые, всё равно соответствует строке выше, поскольку строка выбирается по статусу:

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• analysis_enqueue_failed
• aspect_conflict
• asset_cap_exceeded
• asset_ingest_cap_exceeded
• asset_not_found
• asset_not_ready
• assets_disabled
• creator_profile_limited
• creator_profile_not_found
• creator_url_unsupported
• debt_outstanding
• deletion_held
• edit_ceiling_reached
• edit_conflict
• edit_invalid
• editing_disabled
• editing_not_priced
• editing_window_not_set
• feedback_limited
• generations_disabled
• generations_marking_pending
• idempotency_key_required
• idempotency_key_reused
• ingest_enqueue_failed
• insufficient_credits
• insufficient_scope
• internal_error
• invalid_image
• invalid_request
• malformed_body
• no_changes
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• reference_analysis_disabled
• reference_analysis_limited
• reference_analysis_not_found
• reference_not_analyzable
• reference_not_usable
• reference_url_unsupported
• rejected_field
• revision_needs_generated_unit
• rights_not_confirmed
• run_media_in_use
• run_not_editable
• run_not_finished
• run_not_found
• script_encoding_lost
• source_aspect_mismatch
• source_not_usable
• trend_search_limited
• trend_search_not_found
• trends_unavailable
• unauthorized
• unknown_field
• unsupported_combination
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upload_digest_mismatch
• upload_expired
• upload_in_use
• upload_not_finished
• upload_size_mismatch
• upstream_error
• url_fetch_busy
• url_fetch_failed
• url_fetch_rate_limited
• url_fetch_refused
• url_import_disabled
• workflow_conflict
• workflow_invalid
• workflow_not_ready

11

Ограничения

• 60 платных запросов и 300 бесплатных за 60 секунд. Интервал считается для аккаунта, а не для ключа, поэтому дополнительные ключи не увеличивают пропускную способность.
• Для каждого аккаунта одновременно создаются 3 видео с ведущим и 2 видео без ведущего; остальные ставятся в очередь, а не отклоняются. Если одновременно рендерится много аккаунтов, выполнение также может ждать своей очереди.
• При отказе из-за ограничения частоты запросов время ожидания в секундах указывается в Retry-After и в теле ответа. Учитывайте большее из двух значений.
• Не более 99 вставок на клип и не более 16 появлений актёра между ними. Оба значения рассчитываются по переданным вами индексам слов, поэтому запрос с превышением лимита отклоняется до списания средств.
• cover_words указывает, сколько произносимых слов охватывает вставка, начиная с первого слова её якоря. Вставка заканчивается там, где начинается первое неохваченное слово, поэтому две вставки с соприкасающимися интервалами покрытия идут подряд, без кадра с актёром между ними.
• Доля слов, оставленных без покрытия, определяет долю клипа с лицом и не зависит от скорости речи. Длина слов различается: для сценария на 560 слов запрос на 19% даёт примерно от 16 до 22; для более короткого сценария разброс шире, а другой голос изменит результат.
• Два варианта с одним словом меняют цену, а не только внешний вид. Вставка с якорем на слове 0 захватывает паузу перед первым словом; якорь на слове 1 оставляет дополнительное появление актёра, а каждое появление увеличивает цену. Покрытие, доходящее до последнего слова, продлевает клип до конца и таким же образом убирает заключительное появление.
• В расценке доля указана в поле estimatedFaceWordShare. Используйте это поле; не делите estimatedFaceSeconds на estimatedTotalDurationSec. Эти значения отвечают на разные вопросы: первое — это резерв, рассчитанный для нижней границы диапазона скорости речи, второе — ожидаемая длительность клипа. Их отношение не является долей чего-либо.

12

Чего этот API никогда не делает

• Ничего не публикует. Мы возвращаем файл и подписанную ссылку; вы сами решаете, куда их отправить.
• Не отменяет запущенное выполнение. Для этого нет конечной точки.
• Не принимает следующие поля make_ugc: character, broll_url, disclosure_overlay, webhook_url. Они отклоняются по имени до списания средств, а не принимаются и молча игнорируются.
• Не меняет запрошенный формат или разрешение без уведомления. Несоответствие либо автоматически исправляется с предупреждением, либо приводит к отказу до платного вызова.
• Не отправляет вам обратные вызовы. Вебхуков нет: получайте данные о выполнении через GET /v1/runs/{id}.
• Не показывает ключ повторно и не восстанавливает его из резервной копии.

13

Также полезно знать

• Предупреждения вместо молчания. Всё, что не удалось выполнить, возвращается в warnings[] для того же выполнения с указанием причины. Параметр никогда не исчезает без пояснения.
• MCP-сервер. @clipwright/mcp-server предоставляет тот же контракт в виде инструментов, а tools/list — машиночитаемое представление этой страницы.