К содержанию
Руководство · API v1

Документация ClipMatrix

От первой записи до готового клипа. Начните в студии или соберите свой процесс на публичном API.

Первый клип в студии

Для обычной работы API не нужен. Откройте студию ClipMatrix, войдите в аккаунт и создайте проект.

  1. Добавьте запись. Вставьте ссылку на видео или загрузите файл. Дождитесь импорта и проверки исходника.
  2. Запустите обработку. Выберите язык и настройки отбора. ClipMatrix подготовит варианты клипов; их количество зависит от материала.
  3. Проверьте отбор. Посмотрите начало, концовку и смысл каждого фрагмента. Пометка о необходимости проверки — повод открыть клип перед публикацией.
  4. Доведите в редакторе. Настройте границы, формат кадра, расположение людей и субтитры. Проверьте написание имён и терминов.
  5. Соберите и скачайте. После правок дождитесь актуальной сборки. Проверьте готовый файл со звуком перед публикацией.

Минуты исходника, хранение и другие ограничения доступны в тарифах и аккаунте. Для автоматизации продолжайте с раздела о токенах.

Доступ и 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}'
ПараметрЗначение
languageauto, 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: он возвращает доступность и параметры загрузки. Дальше работайте с размерами и адресами из ответов сервера.

  1. Создайте загрузку через POST /uploads. Передайте имя, фактический размер файла и новый UUID в idempotency_key. При повторе той же загрузки сохраняйте ключ и параметры.
{
  "filename": "recording.mp4",
  "size_bytes": 104857600,
  "idempotency_key": "example-upload-key",
  "language": "auto"
}
  1. Сохраните id загрузки и project_id. Ответ также содержит part_size_bytes, parts_count, parallel_parts и expires_at.
  2. Запросите адреса частей через POST /uploads/{id}/parts с {"part_numbers":[1,2,3]}. Один запрос принимает до 12 номеров.
  3. Отправьте каждую часть PUT-запросом на выданный URL. Соблюдайте offset_bytes, size_bytes, выданные заголовки и Content-Length. Не передавайте токен ClipMatrix хранилищу. Загружайте не больше 3 частей одновременно и учитывайте parallel_parts.
  4. После передачи всех частей вызовите POST /uploads/{id}/complete с {}. Ответ 202 запускает проверку файла.
  5. Дождитесь 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-загрузки.

СЛЕДУЮЩИЙ ШАГ

Попробуйте на своём видео.

Начать бесплатно ↗