Clipwright

Clipwright API

Один HTTP API, который превращает сценарий в липсинк-видео формата UGC. Он создан для управления агентом: каждый вызов — это один JSON-запрос, каждый отказ объясняет, что делать дальше, и ничего нигде не публикуется. Каждое слово этой страницы также является одним markdown-файлом по адресу https://clipwright.io/docs.md, и кратким контрактом для агентов по адресу https://clipwright.io/llms.txt.

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

Каждый вызов направляется на 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 из простого сценария: 30 кредитов за каждую секунду готового видео, округление вверх до целой секунды.
• make_ugc с сегментами или вставками: 10 кредитов за каждую секунду, когда лицо на экране, и минимум 400 кредитов за доставленное видео. Секунды без лица ничего не стоят, а запуск, не доставивший файл, не стоит ничего, даже если вендор уже был оплачен. Время лица суммируется по всему видео и округляется вверх один раз, а не по сегментам. Эти поля требуют долгосрочной квалификации на развертывании; где она отключена, они отклоняются по имени до списания средств.
• create_actor с качеством medium: 10 кредитов за портрет и 10 за каждый дополнительный формат.
• create_actor с качеством high: 20 кредитов за портрет и 20 за каждый дополнительный формат.
• Кредиты покупаются пакетами: 1000 кредитов за $10.00, один платеж, без подписки.

Спрашивайте перед тратой: конечная точка оценки любого навыка ничего не стоит. Ценность ее ответа зависит от навыка.

• make_ugc: оценка — это приблизительный расчет по словам сценария. Списание соответствует тому, что было измерено в готовом видео — его длительности по метру простого сценария, его секундам лица по метру лица — поэтому счет может оказаться выше или ниже оценки.
• create_actor: оценка оценивает каждый запрошенный вами формат, что является максимумом, который вы можете заплатить. Вы платите за портрет и за фактически опубликованные варианты; формат, который не получился, указан в warnings[] и ничего не стоит.

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

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

04

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

Конечная точка	Стоимость в кредитах	Что делает
GET /health	нет	Проверка работоспособности самого API. Отвечает без ключа.
GET /v1/voices	нет	Голоса, которые можно указать в voice или voice_id.
GET /v1/account	нет	Баланс, задолженность и удержания аккаунта, связанного с ключом.
POST /v1/skills/make_ugc/quote	нет	Оценивает вызов make_ugc с этими данными. Ничего не списывает.
GET /v1/runs/{id}	нет	Состояние одного запуска любого навыка, его предупреждения и url видео.
POST /v1/skills/make_ugc/run	да	Запускает видеозапуск и сразу отвечает run_id. Опрашивайте запуск для получения результата.
GET /v1/public/skills	нет	Каталог навыков и их входных данных, без ключа.
GET /v1/actors	нет	Актеры, сохраненные на аккаунте, с id, который принимает make_ugc.
DELETE /v1/actors/{id}	нет	Забывает сохраненного актера. Актер, используемый активным запуском, сохраняется.
GET /v1/actors/{id}/defaults	нет	Читает политику по умолчанию сохраненного актера для людей во вставках.
POST /v1/actors/{id}/defaults	нет	Устанавливает политику по умолчанию сохраненного актера для людей во вставках. Запуск может ее переопределить.
POST /v1/skills/create_actor/quote	нет	Оценивает вызов create_actor с этими данными. Ничего не списывает.
POST /v1/skills/create_actor/run	да	Запускает актерский запуск и сразу отвечает run_id. Опрашивайте запуск для получения результата.
POST /v1/uploads	нет	Принимает байты изображения и возвращает https url, который принимают make_ugc и create_actor.

Запуск любого навыка считывается из одного места, GET /v1/runs/{id}, и проходит через следующие состояния: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

05

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

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

Вызовите quote_ugc перед генерацией и покажите стоимость. Это НЕ ожидает видео: он запускает запуск и возвращает run_id НЕМЕДЛЕННО. Затем вы ДОЛЖНЫ опрашивать get_run с этим run_id, пока состояние не станет 'succeeded' (video_url) или 'failed'. Запуск 'failed', чью оплаченную работу вендора мы все еще удерживаем, может вернуться в 'queued' и позже достичь 'succeeded'; когда это происходит, он указывается в warnings[]. Передайте attempt=2,3,… для намеренного запуска НОВОГО запуска для тех же данных (повтор после неудачи).

Поле	Обязательное	Что означает
script	необязательное	Слова, которые говорит актер; обязательно, если segments не предоставляет произносимый текст. Сегменты и текстово-привязанные вставки требуют долгосрочной квалификации на сервере. Лимиты сценария по речевой модели: eleven_v3: 5000 символов; eleven_flash_v2_5: 10000 символов; eleven_turbo_v2_5: 10000 символов. Подсчет включает пробелы, аудиотеги и знаки ударения; эмодзи могут считаться как два символа. Лимита по количеству слов нет. Длительность и цена — оценки до измерения. Русское ударение: напишите ударную гласную заглавной внутри слова в нижнем регистре ("потОм", "зАмок"), и eleven_v3 получит его как знак ударения U+0301 ("пото́м"); знак, введенный напрямую, сохраняется. Заглавная буква в начале слова остается заглавной, а слово со второй заглавной или заглавной согласной внутри (все заглавные, "ВУЗы") оставляется как есть. Одиночная заглавная гласная внутри слова всегда читается как ударение, поэтому пишите "Яндекс Еда", а не "ЯндексЕда". Сообщите пользователям, пишущим на русском, что они могут так отмечать ударение. eleven_flash_v2_5 и eleven_turbo_v2_5 стоят меньше, но неправильно читают знаки ударения: заглавные доходят до них без изменений.
segments	необязательное	Упорядоченные сегменты актера и изображений; требует долгосрочной квалификации на сервере, captions=false и 1080p. Медиа с изображениями требует явного broll_policy=anyone.
inserts	необязательное	Текстово-привязанные вставки изображений поверх полного озвучивания, каждая покрывает cover_words произнесенных слов от своей привязки; требует долгосрочной квалификации на сервере, captions=false, 1080p и явного broll_policy=anyone.
person	необязательное	NOT HONORED YET: person не поддерживается: этот запрос использует актера по умолчанию; выберите actor_id из list_actors или укажите image для выбора другого лица
actor_id	необязательное	Сохраненный ID актера Clipwright из list_actors. Выберите actor_id, image или person; не комбинируйте их. Без voice или voice_id голос следует полу актера. Не комбинируйте с actor_gender.
image	необязательное	Публичный https url фото актера (PNG, JPEG или WebP, до 10 МБ). Файл на диске сначала проходит через upload_image (POST /v1/uploads) — передайте url, который он возвращает. Источник, который мы не можем использовать — частный хост или loopback, http, недоступный, перенаправляющий, более 10 МБ или не один из этих типов изображений — отклоняется (unusable_source) до списания средств. Мы не определяем пол лица: передайте actor_gender или voice, иначе используется мужской голос по умолчанию с предупреждением.
actor_gender	необязательное	Пол лица в image: female | male. Только с image: выбирает голос по умолчанию этого пола (female: sarah, male: george). Отклоняется с actor_id (его пол известен) и без image. Явный voice или voice_id имеет приоритет, и ответ предупреждает, что actor_gender ничего не изменил.
name	необязательное	NOT HONORED YET: name не поддерживается: он не доходит до рендерера
broll_policy	необязательное	STORED ONLY: Сохраненная политика для B-roll: anyone разрешает людей, включая актера; no_actor исключает актера; no_people исключает всех людей, включая руки. Генерация сегментированного медиа закрыта. Эта настройка только сохраняется и не влияет на видео только с актером. Переопределение запуска побеждает актерское значение по умолчанию; иначе no_people.
captions	необязательное	NOT HONORED YET: субтитры запрошены, но не рендерятся в этом прототипе (этап-B)
caption_style	необязательное	NOT HONORED YET: caption_style не поддерживается: субтитры не рендерятся в этом прототипе (этап-B)
look	необязательное	NOT HONORED YET: look не поддерживается: он не доходит до рендерера
aspect_ratio	необязательное	Формат вывода: 9:16 | 1:1 | 16:9. Если опущено, означает 9:16, и источник другой формы подгоняется к 9:16 с предупреждением — передавайте его явно всегда, когда передаете image. Несоответствие более 15% между запросом и источником отклоняется (aspect_conflict) до списания средств.
resolution	необязательное	Разрешение вывода: 720p | 1080p | 4k (короткая сторона 720 / 1080 / 2160 px). Если опущено, означает 1080p.
voice	необязательное	Имя голоса из list_voices. Курируемые пресеты: owner_ru_clone | sarah | george | eric | daria_ru_female (owner_ru_clone — русский клонированный голос). API отклоняет имя, которое list_voices не возвращает, до списания средств. Если опущено, означает голос по умолчанию для пола актера: пол actor_id, actor_gender с image, или george для актера по умолчанию и для image без actor_gender. Взаимоисключающе с voice_id.
voice_id	необязательное	Сырой ID голоса вендора (16–32 буквы и цифры) для голоса вне каталога. Проверяется лениво: неизвестный id приводит к сбою запуска, а не запроса. Взаимоисключающе с voice.
tts_model	необязательное	Речевая модель: eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5. Если опущено, означает модель выбранного пресета (list_voices показывает ее; каждый пресет говорит на eleven_v3) или eleven_v3 для сырого voice_id. eleven_v3 — самая выразительная и единственная, которая читает знаки ударения (заглавная гласная внутри русского слова, "потОм", становится одним; см. script); eleven_flash_v2_5 и eleven_turbo_v2_5 — более дешевые альтернативы для языков, кроме русского. Лимиты сценария по речевой модели: eleven_v3: 5000 символов; eleven_flash_v2_5: 10000 символов; eleven_turbo_v2_5: 10000 символов. Подсчет включает пробелы, аудиотеги и знаки ударения; эмодзи могут считаться как два символа. Лимита по количеству слов нет. Длительность и цена — оценки до измерения.
disclosure_overlay	необязательное	Допустимые значения: true | false.
background	необязательное	Допустимые значения: white | blur | contain.

create_actor. Создайте личного актера для этого аккаунта из слов, описывающих вымышленного взрослого: портрет 9:16 ровно с одним лицом, плюс другие запрошенные форматы, отредактированные из него. Возвращает run_id немедленно; опрашивайте get_run, пока не получите 'succeeded' (created_actor.actor_id, затем передайте его как actor_id в make_ugc) или 'failed'. Каждое опубликованное изображение оплачивается по цене, которую показывает оценка; отклоненные описания и непригодные портреты ничего не стоят. Когда генерация отключена, вызов завершается с ошибкой actor_generation_disabled.

Поле	Обязательность	Что означает
description	обязательно	Слова, описывающие вымышленного взрослого: внешность, одежда, обстановка. Упоминание реального человека или сходства с ним отклоняется до любого списания (actor_prompt_refused).
gender	обязательно	female | male. Задаёт пол актёра и голос по умолчанию для видео с этим актёром.
approximate_age	обязательно	Примерный возраст в годах, от 18 до 90: актёры — взрослые.
name	обязательно	Имя, отображаемое в list_actors.
aspect_ratios	необязательно	Форматы для создания: 9:16 | 1:1 | 16:9, всегда включая 9:16. Если опущено — все три. Форматы, не прошедшие проверку личности, не списываются и указываются в предупреждениях.
quality	необязательно	Качество изображения: medium | high. Если опущено — medium. Цена за изображение зависит от этого; в расценке это указывается до любого списания.

Формат вывода соответствует запросу и источнику. Поддерживаемые форматы: 9:16, 1:1, 16:9 и разрешения 720p, 1080p, 4k; если не указано — 1080p в 9:16.

06

Запуск выполнения

Платный вызов несёт один заголовок помимо ключа: Idempotency-Key. POST /v1/skills/make_ugc/run и POST /v1/skills/create_actor/run требуют его, и вызов без него отклоняется с кодом 400 idempotency_key_required до любого списания.

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

07

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

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

Отказ	HTTP	Повторить тот же вызов?	Что делать
rate_limited	429	да, после ожидания	Обратное давление, а не ошибка: ответ указывает секунды ожидания в Retry-After и в теле.
server_error	500, 502, 503	да, после ожидания	Сбой на стороне сервера. Не запускайте второе выполнение с новым ключом идемпотентности: тот же вызов и есть повторная попытка.
insufficient_credits	402	нет, ответ будет тем же	Остановитесь и сообщите человеку баланс и цену; оба значения есть в теле. Повтор не изменит ни то, ни другое.
debt_outstanding	402	нет, ответ будет тем же	Остановитесь. Покупка кредитов погашает долг до того, как средства поступят на баланс, и это снимает блокировку.
not_admitted	403	нет, ответ будет тем же	Остановитесь. У аккаунта нет бета-доступа; ни повтор, ни покупка этого не изменят. Обратитесь к оператору.
client_error	400, 401, 404, 409, 413, 415	нет, ответ будет тем же	Остановитесь. Сам запрос был отклонён: прочитайте сообщение, исправьте вызов и отправьте снова.

Это все коды, которые API помещает в error.code. Незнакомый код всё равно подчиняется строке выше, поскольку строка выбирается по статусу:

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

08

Ограничения

• 60 платных запросов и 300 бесплатных за 60 секунд. Окно считается на аккаунт, а не на ключ, поэтому дополнительные ключи не дают дополнительной пропускной способности.
• Одновременно выполняется 3 рендера на аккаунт; остальные ставятся в очередь и не отклоняются.
• Отказ по лимиту скорости указывает секунды ожидания в Retry-After и в теле. Соблюдайте большее из двух значений.
• 49 вставок на клип и не более 6 появлений актёра между ними. Оба значения считаются по индексам слов, которые вы отправляете, поэтому входные данные, запрашивающие больше, отклоняются до любой оплаты.
• cover_words указывает, сколько произнесённых слов покрывает вставка, считая с первого слова её якоря. Вставка заканчивается там, где начинается первое непокрытое слово, поэтому две вставки, чьё покрытие смыкается, являются смежными и не оставляют кадра актёра между ними.
• Доля слов, которые вы оставляете непокрытыми, определяет долю клипа с лицом, и она не зависит от скорости речи. Длина слов варьируется: при сценарии на 560 слов запрос 19% давал от 16 до 22 в девятистах девяноста семи из тысячи смоделированных запусков и оставался в пределах 15–24 в пятидесяти тысячах. Эти цифры измерены на голосе этого профиля и при такой длине; более короткий сценарий даёт больший разброс, а другой голос сдвигает их.
• Два выбора одного слова меняют цену, а не только вид. Вставка с якорем на слове 0 владеет тишиной перед первым словом; с якорем на слове 1 она оставляет дополнительное появление актёра, и каждое появление — отдельная платная задача. Покрытие, достигающее последнего слова, доводит клип до конца и убирает финальное появление так же.
• Расценка сообщает долю как estimatedFaceWordShare. Читайте это поле; не делите estimatedFaceSeconds на estimatedTotalDurationSec. Эти два значения отвечают на разные вопросы — первое это резерв на медленном конце диапазона речи, второе — ожидаемая длительность клипа — и их отношение не является долей чего-либо.

09

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

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

10

Также стоит знать

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