Документация ClipMatrix
От первой записи до готового клипа. Начните в студии или соберите свой процесс на публичном API.
Первый клип в студии
Для обычной работы API не нужен. Откройте студию ClipMatrix, войдите в аккаунт и создайте проект.
- Добавьте запись. Вставьте ссылку на видео или загрузите файл. Дождитесь импорта и проверки исходника.
- Запустите обработку. Выберите язык и настройки отбора. ClipMatrix подготовит варианты клипов; их количество зависит от материала.
- Проверьте отбор. Посмотрите начало, концовку и смысл каждого фрагмента. Пометка о необходимости проверки — повод открыть клип перед публикацией.
- Доведите в редакторе. Настройте границы, формат кадра, расположение людей и субтитры. Проверьте написание имён и терминов.
- Соберите и скачайте. После правок дождитесь актуальной сборки. Проверьте готовый файл со звуком перед публикацией.
Минуты исходника, хранение и другие ограничения доступны в тарифах и аккаунте. Для автоматизации продолжайте с раздела о токенах.
Доступ и API-токен
Базовый адрес: https://clipmatrix.app/api/v1. Персональные API-токены доступны на действующих тарифах Pro и Max. Создайте токен в настройках аккаунта, задайте название и срок действия. Секрет показывается один раз.
Передавайте токен в заголовке Authorization: Bearer …. Храните его в переменной окружения сервера; не добавляйте в код страницы, репозиторий или публичные логи. Первый запрос ниже проверяет доступ и возвращает аккаунт, квоту и каталог стилей.
export CM_URL='https://clipmatrix.app'
# Bash: enter your token without displaying it.
read -r -s CM_TOKEN
export CM_TOKEN
curl --fail-with-body "$CM_URL/api/v1/account" \
-H "Authorization: Bearer $CM_TOKEN"Примеры рассчитаны на Bash, curl и uuidgen. Заменяйте значения YOUR_… своими ссылками и идентификаторами. Не вставляйте токен прямо в команды.
У аккаунта может быть до 20 активных токенов. Истёкший или отозванный токен возвращает 401; отсутствие подходящего действующего тарифа — 403 api_plan_required. API видит только проекты владельца токена.
Импорт записи
POST /projects создаёт проект и запускает импорт по ссылке. Ответ 202 означает, что запрос принят: исходник ещё может загружаться. Сохраните id из ответа.
# Create once; keep this key for retries of the same import.
CM_IMPORT_KEY=$(uuidgen)
curl --fail-with-body -X POST "$CM_URL/api/v1/projects" \
-H "Authorization: Bearer $CM_TOKEN" \
-H "Idempotency-Key: $CM_IMPORT_KEY" \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.youtube.com/watch?v=YOUR_VIDEO","language":"auto"}'Поле url обязательно. title необязательно, от 1 до 180 символов; language — auto, ru или en. Вместо ссылки можно использовать загрузку файла.
# Replace this with the id returned by POST /projects.
CM_PROJECT_ID='YOUR_PROJECT_ID'
curl --fail-with-body "$CM_URL/api/v1/projects/$CM_PROJECT_ID" \
-H "Authorization: Bearer $CM_TOKEN"Опрашивайте проект примерно раз в 3 секунды. Пока job.status равен queued или running, ждите. При error или cancelled остановите цепочку и изучите ошибку. После успешного завершения импорта отдельно запустите обработку.
Создание проекта само по себе не запускает отбор клипов и не списывает минуты обработки.
Обработка и выбор клипов
POST /projects/{pid}/process запускает отбор и расходует минуты исходника по правилам тарифа. Вызывайте его после готовности записи. Сохраняйте ключ запроса для безопасного повтора при обрыве соединения.
CM_PROCESS_KEY=$(uuidgen)
curl --fail-with-body -X POST \
"$CM_URL/api/v1/projects/$CM_PROJECT_ID/process" \
-H "Authorization: Bearer $CM_TOKEN" \
-H "Idempotency-Key: $CM_PROCESS_KEY" \
-H 'Content-Type: application/json' \
-d '{"language":"auto","count":3,"target_seconds":60}'| Параметр | Значение |
|---|---|
language | auto, ru или en. |
count | От 1 до 200. Верхняя граница количества кандидатов, а не обещание найти столько клипов. |
target_seconds | От 20 до 180. Целевая длительность при отборе. |
Следите за GET /projects/{pid}. После завершения получите список клипов:
curl --fail-with-body \
"$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips?offset=0&limit=20" \
-H "Authorization: Bearer $CM_TOKEN"Ответ содержит clips, total, offset и limit. Максимум одной страницы — 50 клипов. Пустой список допустим: материал может не дать подходящих фрагментов.
editorial_status: ready означает, что отбор не требует отдельной ручной проверки; review требует просмотра. Прочитайте editorial_note. Эти поля не означают, что MP4 уже собран: для файла проверяется отдельный render.status.
Рендер, MP4 и субтитры
Запустите сборку выбранного клипа. Ответ 202 подтверждает приём запроса, а не готовность файла. Если актуальная версия уже собрана, повторная сборка не запускается.
# Use a clip id returned by the clips endpoint.
CM_CLIP_ID='YOUR_CLIP_ID'
CM_RENDER_KEY=$(uuidgen)
curl --fail-with-body -X POST \
"$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID/render" \
-H "Authorization: Bearer $CM_TOKEN" \
-H "Idempotency-Key: $CM_RENDER_KEY" \
-H 'Content-Type: application/json' -d '{}'
curl --fail-with-body \
"$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID" \
-H "Authorization: Bearer $CM_TOKEN"Дождитесь render.status: ready в ответе клипа. Для нескольких клипов используйте POST /projects/{pid}/clips/render с телом {"clip_ids":["id1","id2"]}; допускается до 200 ID. Экспорт не списывает минуты исходника, но учитывается в лимите попыток рендера.
Готовый файл
Финальный POST …/download возвращает download_url, способ авторизации и срок ссылки. Он также применяет однократный бонус за брендинг, если клипу положен бонус по правилам сервиса.
curl --fail-with-body -X POST \
"$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID/download" \
-H "Authorization: Bearer $CM_TOKEN" \
-H 'Content-Type: application/json' -d '{}'
curl --fail-with-body \
"$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID/subtitles?format=srt" \
-H "Authorization: Bearer $CM_TOKEN" -o clip.srtПри authentication: signed_url скачайте download_url обычным GET без заголовка Authorization. Ссылка действует до 300 секунд: не храните её как постоянный адрес файла. При authentication: bearer это защищённый API-маршрут, которому нужен токен.
Субтитры доступны в srt, vtt и txt и соответствуют готовому экспорту с его монтажом. Их API-адреса требуют Bearer. При отдельной ошибке субтитров готовый MP4 может оставаться доступным.
Полный исходник: GET /projects/{pid}/source. Он возвращает временный адрес до 1 часа. Если оригинал ещё не готов, сервер отвечает 409 source_not_ready.
Тексты, стиль и кадрирование
PATCH /projects/{pid}/clips/{cid} меняет указанные поля одного клипа. Непереданные настройки сохраняются. Для названия допустимо до 160 символов, для описания — 300, для хэштегов — до 5 элементов вида #слово.
curl --fail-with-body -X PATCH \
"$CM_URL/api/v1/projects/$CM_PROJECT_ID/clips/$CM_CLIP_ID" \
-H "Authorization: Bearer $CM_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"description":"A useful moment from the conversation","hashtags":["#ClipMatrix"]}'Описание и хэштеги меняют текст публикации без нового отбора и рендера. Изменение названия, границ, стиля или кадрирования может запустить пересборку. start и end задаются в абсолютных секундах исходной записи.
Формат и субтитры
Поля aspect и caption_preset доступны и при обработке проекта, и в PATCH клипа. Используйте 9:16, 1:1 или 16:9; идентификаторы стилей берите из caption_presets ответа GET /account. Полную схему объекта captions смотрите в OpenAPI.
Кадрирование без потери правок
GET клипа возвращает framing.version. Для правки передайте эту версию вместе с camera, scenes и/или speaker_zoom. Массив scenes передаётся целиком, времена сцен считаются от начала исходника. При 409 edit_conflict прочитайте свежие данные перед повтором.
Для режима с автоматическим слежением за говорящим есть POST …/clips/{cid}/speaker. Дождитесь speaker_analysis.status: ready, затем вызывайте рендер. До готовности анализа возможен 409 speaker_analysis_required.
Если правка сохранилась, но сервер отказал в постановке сборки, сначала устраните причину отказа, затем вызовите render. Повторно отправлять весь PATCH не требуется.
Загрузка файла частями
Для локального файла используйте multipart-загрузку. Сначала запросите GET /uploads/config: он возвращает доступность и параметры загрузки. Дальше работайте с размерами и адресами из ответов сервера.
- Создайте загрузку через
POST /uploads. Передайте имя, фактический размер файла и новый UUID вidempotency_key. При повторе той же загрузки сохраняйте ключ и параметры.
{
"filename": "recording.mp4",
"size_bytes": 104857600,
"idempotency_key": "example-upload-key",
"language": "auto"
}- Сохраните
idзагрузки иproject_id. Ответ также содержитpart_size_bytes,parts_count,parallel_partsиexpires_at. - Запросите адреса частей через
POST /uploads/{id}/partsс{"part_numbers":[1,2,3]}. Один запрос принимает до 12 номеров. - Отправьте каждую часть PUT-запросом на выданный URL. Соблюдайте
offset_bytes,size_bytes, выданные заголовки и Content-Length. Не передавайте токен ClipMatrix хранилищу. Загружайте не больше 3 частей одновременно и учитывайтеparallel_parts. - После передачи всех частей вызовите
POST /uploads/{id}/completeс{}. Ответ202запускает проверку файла. - Дождитесь
state: readyвGET /uploads/{id}, затем запуститеprocessпроекта.
Размер в примере — 100 МиБ: замените его фактическим размером файла, а UUID — собственным. GET /uploads/{id} также позволяет узнать уже загруженные части и возобновить передачу. DELETE /uploads/{id} отменяет незавершённую загрузку.
Передача файла не списывает минуты обработки. Ограничения на размер, длительность, хранение и доступные минуты проверяются по правилам аккаунта.
Статусы и безопасные повторы
По умолчанию действует лимит 60 запросов в минуту на токен. При 429 rate_limited учитывайте Retry-After. Публичных вебхуков в API v1 нет; используйте опрос примерно раз в 3 секунды с учётом общего лимита всех задач.
render.status | Действие клиента |
|---|---|
none | Актуальной готовой сборки нет. При необходимости запросите рендер. |
queued | Клип принят в очередь. Продолжайте опрос. |
running | Идёт сборка этого клипа. Дождитесь завершения. |
ready | Текущий файл готов к скачиванию. |
failed | Прочитайте render.error и устраните причину перед повтором. |
Состояние проекта и отдельного клипа различается: уже готовый клип может быть доступен даже при ошибке другой части пакетной задачи. Для новых интеграций используйте render; build_status оставлен для совместимости. Неизвестный прогресс может быть null.
Idempotency-Key
Заголовок поддерживается для создания проекта, обработки и одиночного или пакетного рендера. Создайте один ключ на одно намеренное действие. Повтор того же метода, пути и JSON с тем же ключом в течение 24 часов возвращает исходный ответ без новой операции. Для свежего статуса делайте GET.
Ключ — от 1 до 128 печатных ASCII-символов без пробелов, например UUID. Повторное использование с другим запросом возвращает 409 idempotency_conflict. Новая намеренная обработка требует нового ключа и расходует минуты. Остальные POST/PATCH после сетевой ошибки сначала проверяйте через чтение состояния.
Ошибки и восстановление
Ориентируйтесь на HTTP-статус и машинный error.code, а не на формулировку сообщения. Общая форма ответа:
{
"error": {
"code": "edit_conflict",
"message": "…",
"details": {}
},
"detail": "…"
}| Ответ | Что проверить |
|---|---|
401 invalid_api_token | Наличие заголовка, срок и отзыв токена. Создайте новый токен при необходимости. |
403 api_plan_required | Действующий тариф с доступом к API. |
404 | Идентификаторы и владельца проекта: чужие ресурсы не раскрываются. |
409 render_required | Соберите актуальную версию клипа и дождитесь ready. |
409 edit_conflict | Прочитайте актуальную версию кадрирования и согласуйте правку. |
409 speaker_analysis_required | Дождитесь анализа говорящего перед рендером. |
422 validation_error | Названия полей, типы и допустимые диапазоны. Неизвестные поля не принимаются. |
429 rate_limited | Снизьте частоту и соблюдайте Retry-After. |
429 quota_exceeded | Проверьте квоту аккаунта; частые повторы её не восстановят. |
Ошибка фонового задания приходит в состоянии проекта; ошибка сборки — в render.error. Сохраните код, ID проекта и клипа для обращения в поддержку. Не отправляйте токен или подписанную ссылку на файл.
Справочник методов
У всех путей ниже префикс /api/v1. Запросы с телом используют JSON и Content-Type: application/json. Для полной схемы параметров выполните авторизованный GET /api/v1/openapi.json. Общая схема сервиса доступна в OpenAPI JSON ↗.
| Метод и путь | Назначение |
|---|---|
GET /account | Аккаунт, квота, каталог стилей. |
POST /tokens | Новый токен: name и expires_in_days от 1 до 365. |
GET /tokens | Список токенов без секретов. |
DELETE /tokens/{id} | Отозвать свой токен. |
POST /projects | Импорт по ссылке. |
GET /projects/{pid} | Состояние проекта и задания. |
POST /projects/{pid}/process | Запустить отбор клипов. |
GET /projects/{pid}/clips | Список клипов с пагинацией. |
GET /projects/{pid}/clips/{cid} | Клип, кадрирование и состояние рендера. |
PATCH /projects/{pid}/clips/{cid} | Тексты, границы и оформление клипа. |
POST /projects/{pid}/clips/{cid}/render | Рендер одного клипа. |
POST /projects/{pid}/clips/render | Пакетный рендер выбранных клипов. |
POST /projects/{pid}/clips/{cid}/download | Получить ссылку финального скачивания. |
GET /projects/{pid}/clips/{cid}/subtitles | Субтитры готового экспорта. |
GET /projects/{pid}/source | Временная ссылка на полный исходник. |
GET /branding-assets | Доступный аккаунту каталог брендинга; проверяйте enabled. |
Каталоги отражают доступность функции для аккаунта. Не закрепляйте в интеграции неизвестные ID: читайте каталог и обрабатывайте недоступные варианты. Пошаговая работа с файлами описана в разделе multipart-загрузки.