ClipMaster API

Автоматизуйте ClipMaster з командного рядка, власних скриптів або ШІ-асистента. Ті самі ендпоінти, що й у застосунку, — оплата тими самими токенами, без окремих рахунків.

Потрібен простий текст? Читайте цю сторінку в Markdown — для LLM і агентів. Користуєтеся Claude? Підключіть MCP-сервер замість того щоб викликати ендпоінти вручну.

Огляд

Працюйте з ClipMaster програмно за допомогою ключа API. Кожен ендпоінт поводиться так само, як у застосунку, і має доступ лише до ваших проєктів і кліпів. Доступ до API є на платних планах.

Базовий URL:

https://api.clipmaster.app/api/v1

Автентифікація

Створіть ключ у застосунку в розділі Налаштування → Доступ до API. Повний ключ (cm_live_…) показується лише раз під час створення — збережіть його в надійному місці. Передавайте його як Bearer-токен у заголовку Authorization:

curl https://api.clipmaster.app/api/v1/projects \
  -H "Authorization: Bearer cm_live_xxxxxxxxxxxxxxxxxxxx"

Лише в заголовку. Ключі не приймаються як параметр запиту ?token=.
Ключ прив’язаний до вашого акаунта й діє від вашого імені лише з вашими даними.
Відкликайте ключ будь-коли в налаштуваннях; відкликаний ключ одразу перестає працювати.

Маршрути керування обліковим записом залишаються в застосунку. Ключ повертає 403 session_auth_required для входу/OAuth, виставлення рахунків та оформлення замовлення (читання балансу токенів та використання дозволено), адміністрування, керування ключами API та підключення соціального каналу. Спочатку підключіть свій канал у веб-застосунку — все інше можна скриптувати.

Деякі кінцеві точки є функціями платних планів, позначені нижче назвою функції (наприклад, compilation). На плані без неї вони відповідають 403 subscription_required з цією feature.

Ліміти запитів

120 запитів на хвилину на ключ. Якщо перевищити ліміт, повертається 429 із заголовком Retry-After.

Кінцеві точки ШІ (пропозиції, Автомонтаж, вимірювання аудіо, аранжування) також мають власні ліміти на користувача та відповідають 429 таким же чином.

Швидкий старт

Імпортуйте відео з YouTube, дочекайтеся обробки, а потім отримайте список кліпів і скачайте їх. Задайте це один раз у своїй оболонці:

KEY="cm_live_xxxxxxxxxxxxxxxxxxxx"
BASE="https://api.clipmaster.app/api/v1"

1Імпортуйте відео за URL

Запит

curl -X POST "$BASE/upload/from-url" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "source_url": "https://youtube.com/watch?v=..."
}

Відповідь

{
  "project_id": 123,
  "task_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "message": "Processing started",
  "progress_url": "/api/v1/projects/123/status"
}

2Перевіряйте статус до завершення

Запит

curl "$BASE/projects/123/status" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "status": "completed",
  "progress": 1.0,
  "progress_percent": 100,
  "total_clips": 6,
  "processing_complete": true
}

3Отримайте список створених кліпів

Запит

curl "$BASE/projects/123/clips" \
  -H "Authorization: Bearer $KEY"

Відповідь

[
  {
    "clip_id": 456,
    "start_time": 0.0,
    "end_time": 42.3,
    "description": "Founder explains the pivot",
    "status": "ready"
  }
]

4Експортуйте, потім скачайте

Запит

# Render it (charges tokens) -> {"export_id": 37, "status": "rendering", ...}
curl -X POST "$BASE/projects/123/clips/456/export" \
  -H "Authorization: Bearer $KEY"

# Poll until "status" is "completed"
curl "$BASE/exports/37/status" -H "Authorization: Bearer $KEY"

# The clip's exports, newest first
curl "$BASE/exports?clip_id=456" -H "Authorization: Bearer $KEY"

# Download from the newest completed export's download_url
curl -L "$DOWNLOAD_URL" -o clip.mp4

Скачування — це завжди експорт: кліп, відрендерений зі збереженими субтитрами, ефектами й обрізкою. download_url — підписане посилання на S3, дійсне до наступної 00:00 UTC (щонайменше 30 хвилин), без заголовка авторизації. Для нового посилання знову викличте GET /exports.

Завантаження

Для файлів використовуйте двохетапний потік завантаження; для YouTube — імпорт за URL-адресою. Обидва приймають однакові необов'язкові поля: processing_mode (automatic, semantic або full_video), query, min_duration, orientation, прапорці субтитрів та compilation_format з compilation_prompt для створення добірки, як тільки кліпи будуть готові. Обробка витрачає 1 токен за хвилину вихідного матеріалу.

POST/upload/from-url

Імпортувати URL-адресу YouTube. Обробка починається негайно; опитуйте статус повернутого проєкту. Платно: youtube_import.

Запит

curl -X POST "$BASE/upload/from-url" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "source_url": "https://youtube.com/watch?v=...",
  "orientation": "vertical",
  "compilation_format": "auto"
}

Відповідь

{
  "project_id": 123,
  "task_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "message": "Processing started",
  "metadata": { "duration_sec": 212.4, "resolution": "1920x1080" },
  "progress_url": "/api/v1/projects/123/status"
}

POST/uploads/init

Крок 1 завантаження файлу. Повертає тимчасову адресу для завантаження: надішліть файл POST-запитом на upload.url із повернутими upload.fields без змін, а потім викличте complete.

Запит

curl -X POST "$BASE/uploads/init" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "filename": "talk.mp4",
  "size_bytes": 94371840,
  "sha256": "e3b0c44298fc1c14...",
  "duration_sec": 693.5,
  "content_type": "video/mp4"
}

Відповідь

{
  "project_id": 124,
  "upload": {
    "url": "https://uploads.clipmaster.app",
    "fields": {
      "...": "opaque form fields - send them back unchanged"
    }
  },
  "expires_at": "2026-08-14T21:00:00Z"
}

POST/uploads/{project_id}/complete

Крок 2: підтверджує, що завантаження завершено, і запускає обробку.

Запит

curl -X POST "$BASE/uploads/124/complete" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 124,
  "task_id": "b2c3d4e5-...",
  "message": "Processing started",
  "progress_url": "/api/v1/projects/124/status"
}

POST/uploads/assets

Завантажте логотип, озвучення або файл сцени добірки без браузера. purpose — це logo, narration, scene_video або scene_image (останні два платно: compilation). POST повернуті поля, потім файл останнім, на upload.url протягом 15 хвилин, потім використовуйте asset_key за адресою /users/me/logo/from-upload, /projects/{id}/clips/{clip_id}/logo/from-upload, /compilations/{id}/narration/from-upload або /compilations/{id}/media-scenes (як upload_key).

Запит

curl -X POST "$BASE/uploads/assets" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "logo", "content_type": "image/png", "size_bytes": 20480}'

Відповідь

{
  "asset_key": "originals/staging/42/9f1c2b7e.png",
  "upload": {
    "url": "https://s3.amazonaws.com/...",
    "fields": { "...": "opaque form fields - send them back unchanged" }
  },
  "expires_at": "2026-09-11T21:15:00Z"
}

Статус і кліпи

GET/projects/{id}/status

Перевіряє прогрес обробки. status — одне зі значень: uploading, uploaded, processing, completed, failed.

Запит

curl "$BASE/projects/123/status" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "status": "processing",
  "progress": 0.45,
  "progress_percent": 45,
  "current_step": "Transcription",
  "total_scenes": 8,
  "total_clips": 0,
  "processing_complete": false
}

GET/projects/{id}/clips

Повертає список створених кліпів із ШІ-метаданими (хук, тип кліпу, впевненість).

Запит

curl "$BASE/projects/123/clips" \
  -H "Authorization: Bearer $KEY"

Відповідь

[
  {
    "clip_id": 456,
    "start_time": 0.0,
    "end_time": 42.3,
    "description": "Founder explains the pivot",
    "display_name": null,
    "status": "ready",
    "source": "Clipmaster",
    "streaming_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...",
    "features": {
      "scene_id": 2265,
      "clip_duration": 42.3,
      "vision_analysis": {
        "hook": "The moment everything changed",
        "clip_type": "story",
        "confidence": 0.9
      }
    }
  }
]

GET/projects/{id}/clips/{clip_id}

Повна інформація для одного кліпу — надмножина елемента списку: кожне поле функції, ШІ-аналіз сцени, її відступ, значок та віральність. Кожен кадр, аудіо та слова знаходяться в GET …/analysis.

Запит

curl "$BASE/projects/123/clips/456" \
  -H "Authorization: Bearer $KEY"

Та сама структура, що й елемент списку вище, але з повним об’єктом features.

GET/projects

Повертає список ваших проєктів.

Запит

curl "$BASE/projects" -H "Authorization: Bearer $KEY"

Відповідь

[
  {
    "project_id": 123,
    "filename": "keynote.mp4",
    "status": "completed",
    "created_at": "2026-08-14T20:11:38Z",
    "video_metadata": {
      "duration_sec": 693.5,
      "resolution": "1920x1080",
      "detected_orientation": "horizontal"
    },
    "is_demo": false
  }
]

DELETE/projects/{id}

Видаляє проєкт з усіма його кліпами, сценами й файлами.

Запит

curl -X DELETE "$BASE/projects/123" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "success": true,
  "message": "Project deleted"
}

POST/projects/{id}/transcription

Повторно транскрибувати все відео у фоновому режимі. Кліпи з власними відредагованими словами зберігають їх. Опитуйте статус для project_config.transcription_rerun_status. Без токенів; з обмеженням швидкості.

Запит

curl -X POST "$BASE/projects/123/transcription" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "status": "running",
  "progress_url": "/api/v1/projects/123/status"
}

Аналіз

Прочитайте аналіз у форматі JSON, щоб розмістити редагування на основі знайденого. Документи кліпу використовують час переглядача — годинник накладень, пропозицій та Автомонтажу: секунди від початку сцени. Кліп відтворюється від 0 до time.duration; час поза цим є відступом навколо сцени, куди не можуть потрапити накладення. Список моментів зберігає лише те, що відтворюється, тому кожен його t можна розмістити як є; з повного аналізу кліпу розміщуйте лише час між 0 та time.duration. Секунди відео = t + time.scene_start. Документ відео використовує секунди від початку завантаження. Коробки — це {x, y, w, h} частки кадру. Читання безкоштовне та працює на демо-проєкті.

GET/projects/{id}/clips/{clip_id}/analysis

Весь збережений аналіз кліпу. Розділи: scene (опис, гачок, тема, тип, оцінка, значок, віральність), layout (зміни камери та, для кожного кадру, тип кадру, обличчя та панелі екрана/вебкамери), audio (голосно, тихо, ритм, спів; onsets=true додає кожен удар), transcript (слова кліпу, з динаміками, якщо відомо), sound_events (сміх, оплески, музика), video_moments, talk_scenes та auto_edit (збережений дубль, з його діапазонами швидкості). include вибирає розділи, розділені комами; за замовчуванням усі.

Запит

curl "$BASE/projects/123/clips/456/analysis?include=scene,layout,audio" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "clip_id": 456,
  "scene_id": 2265,
  "time": {
    "clock": "viewer",
    "unit": "seconds",
    "note": "0 = scene start, …",
    "duration": 10.0,
    "scene_start": 100.0,
    "scene_end": 110.0,
    "clip_start": -2.0,
    "clip_end": 12.0
  },
  "analyses": {
    "layout": {
      "status": "completed",
      "error": null,
      "step": null,
      "started_at": "2026-10-22T18:02:11+00:00",
      "finished_at": "2026-10-22T18:02:40+00:00",
      "what": "Faces, screen/webcam/gameplay panels, shot type per frame, camera cuts.",
      "rest": "POST /api/v1/projects/123/clips/456/layout-analysis",
      "mcp": "analyze_clip_layout",
      "cost": "Paid plans (smart crop); no tokens."
    },
    "audio_cues": { "status": "completed", "...": "same fields" },
    "auto_edit": { "status": null, "...": "same fields" }
  },
  "scene": {
    "description": "He grabs the rim and the crowd erupts",
    "hook": "The dunk nobody saw coming",
    "topic": "basketball",
    "clip_type": "reaction",
    "score": 8,
    "...": "the rest of its stored AI fields",
    "badge": { "label": "Highlight", "key": "highlight", "color": "#FF6B6B" },
    "virality": { "tier": "hot", "label": "Hot", "color": "#FF4444" }
  },
  "layout": {
    "current": true,
    "faces_placeable": true,
    "analyzed_at": "2026-10-22T18:02:40+00:00",
    "model": "gemini-3.5-flash-lite",
    "frame_interval": 2.0,
    "frame_size": { "width": 1920, "height": 1080 },
    "cuts": [4.0],
    "frames": [
      { "t": 0.0, "shot": "solo_talking_head",
        "faces": [{ "x": 0.4, "y": 0.1, "w": 0.2, "h": 0.4 }], "panels": [] },
      { "t": 4.0, "shot": "screen_share_with_webcam",
        "faces": [{ "x": 0.8, "y": 0.04, "w": 0.12, "h": 0.18 }],
        "panels": [{ "kind": "webcam_overlay", "x": 0.75, "y": 0.0, "w": 0.25, "h": 0.25,
                     "highlighted": true }] }
    ]
  },
  "audio": {
    "current": true,
    "measured_at": "2026-10-22T18:01:05+00:00",
    "has_audio": true,
    "median_active_db": -20.0,
    "loud": [{ "t": 4.0, "end": 4.5, "over_db": 9.0 }],
    "quiet": [{ "start": -2.0, "end": -0.5, "level_db": -48.0 }],
    "beat": [{ "start": 0.0, "end": 10.0, "tempo_bpm": 120.0, "first_beat": 0.1, "period": 0.5 }],
    "singing": null
  }
}

time та analyses завжди присутні. analyses має один запис на запуск за запитом (layout, audio_cues, auto_edit): status — running (виконується), completed (завершено), failed (невдало), stale (позначено як виконується понад 30 хвилин, тому, ймовірно, померло — перевірте ще раз перед перезапуском) або null (ніколи не запускалося), з error, step (останній досягнутий крок; має значення під час виконання), мітками часу та кінцевою точкою, яка його запускає. layout, audio та auto_edit є null, доки вони не будуть запущені; sound_events, video_moments та talk_scenes є [], коли нічого не знайдено. current: false означає, що результат більше не відповідає кліпу: його відеофайл був знову обрізаний з того часу (одне лише обрізання не змінює його), для layout також, коли останній запуск не завершився, для audio також, коли саме вимірювання змінилося. Обрізання робить auto_edit current: false, оскільки його час відраховується від годинника сцени; старіший дубль, який не записав свою сцену, читається як current: null (невідомо). Час аудіо конвертується з файлу, на якому він був виміряний. Невідомий розділ — 400 unknown_section.

GET/projects/{id}/clips/{clip_id}/moments

Кліп як один відсортований за часом список {t, kind, source, …}: cut, shot та faces (коли змінюється кількість кадрів або облич), зміни speaker, sound, loud, quiet, beat, singing та moments візуального проходу. Перелічується лише те, що відтворюється — проміжки, обрізані до 0–time.duration, кадр, кількість облич або динамік, встановлений у відступі, перенесений до 0, все інше у відступі залишається поза увагою — тому кожен t переходить до POST …/overlays як є. Аналіз макета або аудіо, який більше не відповідає кліпу, виключається та називається в stale. З summary сцени, які аналізи available, та analyses. Той самий годинник, що й аналіз кліпу.

Запит

curl "$BASE/projects/123/clips/456/moments" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "clip_id": 456,
  "time": { "clock": "viewer", "duration": 10.0, "...": "as in …/analysis" },
  "summary": {
    "description": "He grabs the rim and the crowd erupts",
    "hook": "The dunk nobody saw coming",
    "topic": "basketball",
    "clip_type": "reaction",
    "score": 8
  },
  "available": { "layout": true, "audio": true, "transcript": true, "video_moments": true },
  "stale": [],
  "analyses": { "...": "as in …/analysis" },
  "moments": [
    { "t": 0.0, "kind": "beat", "source": "audio", "end": 10.0, "tempo_bpm": 120.0 },
    { "t": 0.0, "kind": "faces", "source": "layout", "count": 1 },
    { "t": 0.0, "kind": "shot", "source": "layout", "detail": "solo_talking_head" },
    { "t": 0.0, "kind": "speaker", "source": "transcript", "speaker": "speaker_0", "first_word": "Here" },
    { "t": 1.0, "kind": "moment", "source": "video", "end": 3.0, "detail": "action_peak",
      "score": 8, "description": "Rim grab" },
    { "t": 3.0, "kind": "sound", "source": "transcript", "end": 4.0, "detail": "laughter" },
    { "t": 4.0, "kind": "cut", "source": "layout" },
    { "t": 4.0, "kind": "loud", "source": "audio", "end": 4.5, "over_db": 9.0 },
    { "t": 4.0, "kind": "shot", "source": "layout", "detail": "screen_share_with_webcam" }
  ]
}

GET/projects/{id}/analysis

Все відео, за часом відео: metadata, transcript за сегментами з динаміками, sound_events, video_moments візуального проходу та talk_scenes проходу транскрипції (кожен з …_status та блоком …_pass: статус та модель проходу, плюс помилка та час візуального проходу), та кожна сцена з її хуком, оцінкою та прапорцем degraded (true: крок сцени ШІ не вдався, і це неоцінений фіксований за довжиною запасний варіант). include вибирає розділи; words (кожне слово, з динаміком та впевненістю) з'являється лише тоді, коли названо. analyses.transcription повідомляє про повторну транскрипцію.

Запит

curl "$BASE/projects/123/analysis" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "time": { "clock": "video", "unit": "seconds", "note": "Seconds from the start of the upload." },
  "analyses": {
    "transcription": {
      "status": null,
      "...": "same fields as a clip's runs",
      "rest": "POST /api/v1/projects/123/transcription",
      "mcp": "transcribe_video"
    }
  },
  "metadata": { "duration_sec": 693.5, "resolution": "1920x1080", "detected_orientation": "horizontal",
                "...": "the rest of the upload's metadata" },
  "transcript": {
    "language": "english",
    "provider": "openai_whisper",
    "duration": 693.5,
    "no_audio": false,
    "speakers": [],
    "segments": [{ "start": 99.0, "end": 106.0, "text": "Here we go.", "speaker": null }]
  },
  "sound_events": [{ "t": 103.0, "end": 104.0, "kind": "laughter", "label": "[laughter]",
                     "speaker": null, "confidence": null }],
  "video_moments": [{ "start": 101.0, "end": 103.0, "type": "action_peak", "score": 8,
                      "description": "Rim grab" }],
  "video_moments_status": "ok",
  "video_moments_pass": { "status": "ok", "error": null, "model": "gemini-3.8-flash",
                          "analyzed_at": "2026-10-22T17:40:12+00:00" },
  "talk_scenes": [{ "start": 95.0, "end": 105.0, "clip_type": "story", "score": 7,
                    "hook": "Why he almost quit", "topic": "basketball",
                    "description": "He tells how the season started", "confidence": 0.8 }],
  "talk_scenes_status": "ok",
  "talk_scenes_pass": { "status": "ok", "model": "gpt-4o-mini" },
  "scenes": [{ "scene_id": 2265, "start": 100.0, "end": 110.0, "source": "merged",
               "description": "He grabs the rim and the crowd erupts",
               "hook": "The dunk nobody saw coming", "topic": "basketball",
               "clip_type": "reaction", "score": 8, "degraded": false }]
}

POST/projects/{id}/clips/{clip_id}/audio-cues

Вимірюйте аудіо кліпу — гучні моменти, тихі ділянки, ритм та темп, спів — у фоновому режимі. Опитуйте GET …/analysis, доки analyses.audio_cues.status не буде завершено або не вдасться; результатом є його розділ audio. Пропозиції та Автомонтаж вимірюють це самостійно; викличте це, щоб спочатку прочитати аудіо. 409 audio_cues_running, audio_cues_current (збережене вимірювання все ще відповідає файлу кліпу) або clip_file_missing. Платно: ai_suggestions; без токенів; ділить ліміт частоти з пропозиціями ефектів та Автомонтажем.

Запит

curl -X POST "$BASE/projects/123/clips/456/audio-cues" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "clip_id": 456,
  "status": "running"
}

Редагування

Все, що робить вбудований редактор, можна скриптувати: обрізка, субтитри та їх переклад, макети, зуми, екранні ефекти, швидкість, емодзі, GIF, стікери, реакційні кліпи, звукові ефекти, логотип, індикатор прогресу та орієнтація.

Два годинники. Накладення, які ви додаєте (POST …/overlays), і кожна пропозиція використовують час переглядача — секунди від початку відтворення кліпу. Збережені налаштування зберігають час відносно файлу кліпу з відступами, на кілька секунд довший з кожного кінця; кінцева точка накладень конвертує для вас.

PUT/projects/{id}/scenes/{scene_id}/boundaries

Обрізка — зсуває початок/кінець кліпу. Усі кліпи сцени оновлюються автоматично.

Запит

curl -X PUT "$BASE/projects/123/scenes/2265/boundaries" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "new_start_time": 12.0,
  "new_end_time": 27.5
}

Відповідь

{
  "scene_id": 2265,
  "project_id": 123,
  "old_start_time": 0.0,
  "old_end_time": 42.3,
  "new_start_time": 12.0,
  "new_end_time": 27.5,
  "message": "Scene boundaries updated successfully."
}

GET · PUT/projects/{id}/clips/{clip_id}/settings

Прочитати або оновити повний стан редактора: субтитри (з secondary для другого рядка), емодзі, GIF, стікери та реакційні кліпи (gifs, розрізняються за kind), звукові ефекти, зум, екранні ефекти, кадрування, логотип, індикатор прогресу, орієнтація, speed та speedRanges. PUT замінює весь об'єкт — відправте назад все, що повернув GET, зі своїми змінами; все, що пропущено, очищається.

Запит

curl -X PUT "$BASE/projects/123/clips/456/settings" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "orientation": "vertical",
  "captions": {
    "enabled": true,
    "style": "hormozi",
    "karaoke": true
  },
  "speed": 1.25
}

Відповідь

{
  "clip_id": 456,
  "settings": {
    "captions": { "enabled": true, "style": "hormozi", "karaoke": true },
    "zoom": null,
    "screenEffects": null,
    "logo": null,
    "progressBar": null,
    "smartCrop": null,
    "gifs": null,
    "orientation": "vertical",
    "speed": 1.25,
    "speedRanges": null
  }
}

Зум – це одна форма: {type: "zoom", start, end, scale, glide, target, center} — вхід на start (glide секунд, щоб дістатися туди, 0 – миттєво), утримання на scale (1.05–2.5), повернення на end, або утримання до кінця кліпу, коли end є null. Старі різкі та повільні зуми конвертуються.

GET · PUT/projects/{id}/clips/{clip_id}/captions

Читає або замінює слова субтитрів із таймінгом для кожного слова.

Запит

curl -X PUT "$BASE/projects/123/clips/456/captions" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "words": [
    { "text": "Use", "start": 28.06, "end": 28.14 },
    { "text": "correct", "start": 28.14, "end": 28.22 }
  ]
}

Відповідь

{
  "words": [
    { "text": "Use", "start": 28.06, "end": 28.14, "highlight": null },
    { "text": "correct", "start": 28.14, "end": 28.22, "highlight": null }
  ]
}

PATCH/projects/{id}/clips/{clip_id}/name

Перейменовує кліп. Порожній рядок повертає згенеровану назву.

Запит

curl -X PATCH "$BASE/projects/123/clips/456/name" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "name": "Best hook"
}

Відповідь

{
  "clip_id": 456,
  "display_name": "Best hook"
}

POST/projects/{id}/clips/{clip_id}/transcribe

Повторно транскрибувати аудіо цього кліпу та зробити результат його субтитрами. Замінює відредаговані слова; відповідає новими словами. Без токенів; з обмеженням швидкості.

Запит

curl -X POST "$BASE/projects/123/clips/456/transcribe" \
  -H "Authorization: Bearer $KEY"

POST/projects/{id}/clips/{clip_id}/overlays

Додайте накладення в час, який бачить глядач: emojis, inline_emojis, gifs, stickers, reaction_clips, sfx, zooms, screen_effects та speed_ranges. Перетворення часу редактора та значення за замовчуванням застосовуються для вас, а пропозиції ШІ можуть бути відправлені у тому вигляді, в якому вони надійшли. Це лише додає.

Запит

curl -X POST "$BASE/projects/123/clips/456/overlays" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "emojis": [{ "emoji": "🔥", "timestamp": 12.0 }],
  "inline_emojis": [{ "emoji": "💰", "word_index": 5 }],
  "gifs": [{ "source_id": "k1", "slug": "mind-blown", "mp4_url": "https://…",
             "width": 480, "height": 270, "timestamp": 8.0 }],
  "sfx": [{ "sfx_id": 3, "timestamp": 3.0, "volume": 0.4 }],
  "zooms": [{ "start": 20.0, "length": 1.0, "scale": 1.3 }],
  "screen_effects": [{ "look": "flash", "start": 20.0 }],
  "speed_ranges": [{ "start": 31.0, "length": 2.5, "speed": 2.0 }]
}

Відповідь

{
  "clip_id": 456,
  "settings": {
    "emojis": [
      { "type": "floating", "emoji": "🔥", "timestamp": 14.0, "duration": 1.0,
        "position": { "x": 0.5, "y": 0.694 }, "scale": 1.0 }
    ],
    "zoom": [
      { "type": "zoom", "start": 22.0, "end": 23.0, "scale": 1.3, "glide": 0,
        "target": "frame", "center": { "x": 0.5, "y": 0.5 } }
    ]
  }
}

Кліп містить до 5 GIF, 5 стікерів та 5 реакційних кліпів. spot на емодзі або стікері слідує за головним обличчям, а target: "face" на зумі збільшує його — платно (smart_crop), після аналізу макета кліпу.

GET · POST/projects/{id}/clips/{clip_id}/translations

Другий рядок субтитрів іншою мовою. GET перераховує мови, які вже має цей кліп, та підтримувані; POST {"language": "es"} перекладає його — 1 токен, безкоштовно, якщо кліп вже має його. Платно: caption_translation. Він відображається, коли captions.secondary встановлено в налаштуваннях.

Запит

curl -X POST "$BASE/projects/123/clips/456/translations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "es"}'

Відповідь

{
  "project_id": 123,
  "language": "es",
  "lines": [{ "text": "Usa la palabra correcta", "start": 28.06, "end": 29.4 }],
  "created": true,
  "tokens_charged": 1
}

POST/projects/{id}/clips/{clip_id}/layout-analysis

Аналізуйте, що показує кожен момент кліпу — типи кадрів, обличчя, панелі екрана та вебкамери — у фоновому режимі. Необхідно, перш ніж накладення зможуть слідувати за обличчям. Опитуйте кліп на features.vision_analysis.layout_rerun_status або GET …/analysis на analyses.layout.status; кожен кадр є його розділом layout. Платно: smart_crop; без токенів.

Запит

curl -X POST "$BASE/projects/123/clips/456/layout-analysis" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "clip_id": 456,
  "status": "running"
}

POST · DELETE/projects/{id}/clips/{clip_id}/logo

Завантажити (multipart, поле file) або видалити логотип для кожного кліпу. Без браузера, підготуйте його за допомогою POST /uploads/assets та прикріпіть за адресою …/logo/from-upload.

Запит

curl -X POST "$BASE/projects/123/clips/456/logo/from-upload" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_key": "originals/staging/42/9f1c2b7e.png"}'

ШІ-пропозиції та Автомонтаж

Пропозиції доступні лише для читання: вони повертають розміщення за часом переглядача, готові до відправлення на POST …/overlays у тому вигляді, в якому вони надійшли. Платно: ai_suggestions. Без токенів; з обмеженням швидкості.

POST/projects/{id}/clips/{clip_id}/{kind}/suggest

Пропозиції для одного кліпу. kind — це gifs, stickers, reaction-clips, emojis, sfx, effects (рецепти зуму та екранних ефектів) або speed (прискорення тиші, уповільнена зйомка). Параметр запиту max_suggestions.

Запит

curl -X POST "$BASE/projects/123/clips/456/gifs/suggest?max_suggestions=3" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "clip_id": 456,
  "suggestions": [
    {
      "source_id": "k1",
      "slug": "mind-blown",
      "title": "Mind Blown",
      "mp4_url": "https://…",
      "width": 480,
      "height": 270,
      "preview_url": "https://…",
      "timestamp": 8.0,
      "duration": 2.0,
      "query": "mind blown",
      "reason": "Reacts to the reveal"
    }
  ]
}

effects та speed відповідають audio_cues_ready: false, поки аудіо кліпу ще вимірюється — запитайте знову через кілька секунд. Пропозиція швидкості: {start, end, speed}: надішліть її з length = end − start.

POST/projects/{id}/clips/{clip_id}/auto-edit

Сплануйте весь монтаж для кліпу — зуми, екранні ефекти, стікери, звуки та діапазони швидкості — у фоновому режимі. Опитуйте кліп на features.vision_analysis.auto_edit_rerun_status; монтаж — це features.vision_analysis.auto_edit ({effects, stickers, sfx, speed}, також розділ auto_edit з GET …/analysis). Нічого не застосовується: надішліть його частини до POST …/overlays. Платно: ai_suggestions; без токенів.

Запит

curl -X POST "$BASE/projects/123/clips/456/auto-edit" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "project_id": 123,
  "clip_id": 456,
  "status": "running"
}

Експорт

POST/projects/{id}/clips/{clip_id}/export

Рендерить кліп зі збереженими налаштуваннями. Повертає id експорту для перевірки статусу; списує токени.

Запит

curl -X POST "$BASE/projects/123/clips/456/export" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "export_id": 37,
  "status": "rendering",
  "message": "Export render triggered"
}

GET/exports/{export_id}/status

Перевіряє статус експорту. Після завершення download_url — тимчасове посилання, яке спливає, тож скачайте файл якнайшвидше.

Запит

curl "$BASE/exports/37/status" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "export_id": 37,
  "status": "completed",
  "download_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...&Expires=...",
  "created_at": "2026-08-14T21:47:35Z",
  "completed_at": "2026-08-14T21:48:42Z"
}

GET/exports

Список ваших експортів, від найновіших. Фільтр: clip_id або project_id. Так скачують кліп: візьміть найновіший експорт зі статусом completed і завантажте його download_url.

Запит

curl "$BASE/exports?clip_id=456" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "exports": [
    {
      "export_id": 37,
      "clip_id": 456,
      "project_id": 123,
      "status": "completed",
      "progress": null,
      "export_number": 2,
      "tokens_charged": 1,
      "clip_duration_sec": 42.3,
      "download_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...&Expires=...",
      "created_at": "2026-08-14T21:47:35Z",
      "completed_at": "2026-08-14T21:48:42Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Добірки

Добірка — це один монтаж, створений з кліпів будь-якого з ваших відео. Створення, аранжування та експорт добірки є платним: compilation.

GET/compilations

Повертає ваші добірки (набори кліпів із різних проєктів).

Запит

curl "$BASE/compilations" -H "Authorization: Bearer $KEY"

Відповідь

{
  "items": [
    {
      "id": 10,
      "name": "Funny Personal Anecdotes",
      "clip_count": 5,
      "total_duration_sec": 149.9,
      "output": { "width": 1920, "height": 1080, "fps": 30 },
      "format": null,
      "latest_export": null,
      "created_at": "2026-08-10T19:05:41Z"
    }
  ]
}

POST/compilations

Створити порожню добірку. Платно: compilation.

Запит

curl -X POST "$BASE/compilations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "name": "Best of March",
  "output": { "width": 1080, "height": 1920, "fps": 30 }
}

GET · PATCH/compilations/{id}

Прочитати одну добірку — її кліпи, estimated_tokens для експорту, план монтажу в arrangement_metadata.edit_plan та файли, які вона відтворює в media — або змінити її name, output, logo_config або progress_bar_config.

Запит

curl "$BASE/compilations/10" -H "Authorization: Bearer $KEY"

GET/compilations/{id}/deletion-preview

Що видалення потягне за собою: завантаження, які існують лише для цієї добірки, та відкладені публікації.

Запит

curl "$BASE/compilations/10/deletion-preview" -H "Authorization: Bearer $KEY"

Відповідь

{
  "compilation_id": 10,
  "source_project_ids": [],
  "scheduled_posts_pending": 0
}

DELETE/compilations/{id}

Видалити добірку; її відкладені публікації скасовуються. delete_sources=true також видаляє завантаження з попереднього перегляду; передайте їх як expected_project_ids, і видалення буде відхилено (409), якщо цей набір змінився.

Запит

curl -X DELETE "$BASE/compilations/10" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "compilation_id": 10,
  "deleted_project_ids": [],
  "scheduled_posts_cancelled": 0
}

GET/compilations/available-clips

Ваші кліпи з усіх відео, щоб додати. Параметри запиту q, limit, offset.

Запит

curl "$BASE/compilations/available-clips?q=pivot&limit=50" \
  -H "Authorization: Bearer $KEY"

POST · DELETE/compilations/{id}/clips

Додайте кліп (clip_id, необов’язково position). DELETE /compilations/{id}/clips/{compilation_clip_id} видаляє один.

Запит

curl -X POST "$BASE/compilations/10/clips" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"clip_id": 456}'

POST/compilations/{id}/clips/suggest

Більше кліпів з вашої бібліотеки, які підходять до цієї добірки, найкращі спочатку.

Запит

curl -X POST "$BASE/compilations/10/clips/suggest" \
  -H "Authorization: Bearer $KEY"

POST/compilations/suggest

Ідеї добірок з вашої бібліотеки для короткого опису. Перетворіть одну на добірку за допомогою POST /compilations/from-suggestion (name, clip_ids).

Запит

curl -X POST "$BASE/compilations/suggest" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "funny moments", "max_suggestions": 3}'

Відповідь

{
  "suggestions": [
    {
      "theme": "Funny moments",
      "reason": "Five clips where the audience laughs",
      "clip_ids": [456, 457, 461],
      "total_duration_sec": 94.2
    }
  ]
}

POST/compilations/{id}/export

Відрендерити добірку. Списує токени за секунди джерела, які вона відтворює (estimated_tokens у добірці).

Запит

curl -X POST "$BASE/compilations/10/export" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "export_id": 5,
  "compilation_id": 10,
  "status": "pending",
  "estimated_tokens": 3,
  "message": "Export started"
}

GET/compilations/{id}/exports/{export_id}/status

Опитування експорту добірки; download_url працює так само, як для експорту кліпу. GET /compilations/{id}/exports перераховує їх.

Запит

curl "$BASE/compilations/10/exports/5/status" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "export_id": 5,
  "compilation_id": 10,
  "status": "completed",
  "progress": null,
  "download_url": "https://clipmaster-media.s3.amazonaws.com/...mp4?...&Expires=...",
  "created_at": "2026-08-14T21:47:35Z",
  "completed_at": "2026-08-14T21:50:02Z"
}

Редагування добірок

Добірка — це план монтажу: сцени з однієї-трьох панелей (кліп або файл) з переходами та текстовими картками, а також накладеннями, музикою та озвученням над усім монтажем. Час вказується в секундах від початку добірки.

POST/compilations/{id}/arrange

Перемонтуйте добірку за допомогою ШІ в новий план сцен. format: custom (монтаж; потрібен prompt), best_of, countdown, trailer, hook_loop, tutorial, qa_highlights або auto. Замінює сцени та закріплені до них емодзі та GIF; субтитри, музика та озвучка залишаються.

Запит

curl -X POST "$BASE/compilations/10/arrange" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "format": "hook_loop"
}

Відповідь

{
  "id": 10,
  "name": "Funny Personal Anecdotes",
  "format": "hook_loop",
  "total_duration_sec": 58.2,
  "estimated_tokens": 1,
  "clips": [
    { "compilation_clip_id": 88, "position": 0, "clip_id": 456, "duration_sec": 12.4, "missing": false }
  ],
  "arrangement_metadata": {
    "resolved_format": "hook_loop",
    "degraded": false,
    "edit_plan": {
      "version": "2.0",
      "scenes": [
        {
          "id": "1",
          "layout": "full",
          "sources": [
            { "clip_id": 456, "slot": 0, "audio": "primary",
              "start_offset_sec": 3.0, "end_offset_sec": 9.5, "speed": 1.0 }
          ],
          "text": []
        }
      ]
    }
  }
}

degraded: true означає, що крок ШІ не вдався, і кліпи були збережені в порядку.

POST/compilations/{id}/plan/undo · reset · place-added-clips

plan/undo повертається до стану до останнього аранжування, скидання або розміщення (знову повторює); plan/reset робить простий виріз, кожен кліп цілий; plan/place-added-clips вставляє додані кліпи в ШІ-монтаж. Без тіла.

Запит

curl -X POST "$BASE/compilations/10/plan/undo" \
  -H "Authorization: Bearer $KEY"

POST/compilations/{id}/scenes/{scene_id}/regenerate

Перемонтуйте одну сцену за допомогою ШІ, залишивши решту. Необов’язковий prompt. Ідентифікатори сцен є текстом.

Запит

curl -X POST "$BASE/compilations/10/scenes/3/regenerate" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "use the boat clip instead"}'

PUT/compilations/{id}/scenes/{scene_id}/beat-pattern

Додає сцені ритмічний патерн: короткі беззвучні повтори її кліпу в такт музиці, одразу перед нею. pattern: stutter, quick_stutter, build_up, jump_cut, teaser або null, щоб прибрати. Потрібна виміряна музика (доти 409 music_not_measured).

Запит

curl -X PUT "$BASE/compilations/10/scenes/3/beat-pattern" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "stutter"}'

PUT/compilations/{id}/plan

Замінити план монтажу. Макет: full (1 панель), stack2 / cols2 / pip (2), stack3 / cols3 (3). Джерело відтворює clip_id або media_key; його зміщення – це початок і кінець вікна в секундах відносно сцени кліпу; щонайбільше одне джерело на сцену є primary аудіо. Переходи: cut, fade, slide, wipe. Залишені накладки зберігаються; пропущена music видаляється.

Запит

curl -X PUT "$BASE/compilations/10/plan" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "version": "2.0",
  "scenes": [
    {
      "id": "1",
      "layout": "full",
      "sources": [{ "clip_id": 456, "audio": "primary",
                    "start_offset_sec": 2.0, "end_offset_sec": 14.5 }],
      "text": [{ "text": "Day one", "role": "title", "start_ms": 0, "duration_ms": 2000 }]
    },
    {
      "id": "2",
      "layout": "stack2",
      "transition_in": { "kind": "fade", "duration_ms": 400 },
      "sources": [
        { "clip_id": 457, "slot": 0, "audio": "primary", "speed": 1.5 },
        { "clip_id": 458, "slot": 1 }
      ]
    }
  ],
  "music": { "track_id": "a1b2c3", "volume": 0.3 }
}

POST · PATCH/compilations/{id}/plan/overlays

POST додає емодзі, GIF, стікери, зуми, екранні ефекти та звукові ефекти до всього монтажу, у формах накладок кліпів. PATCH замінює збережений набір цілком (captions, emojis, gifs, screenEffects, zoom, sfx); змінюється лише те, що ви надсилаєте.

Запит

curl -X POST "$BASE/compilations/10/plan/overlays" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "emojis": [{ "emoji": "🎉", "timestamp": 3.0 }],
  "screen_effects": [{ "look": "bw", "start": 10.0, "length": 2.0 }]
}

Відповідь

{
  "id": 10,
  "arrangement_metadata": {
    "edit_plan": {
      "emojis": [
        { "type": "floating", "emoji": "🎉", "timestamp": 3.0, "duration": 1.0,
          "position": { "x": 0.5, "y": 0.694 }, "scale": 1.0 }
      ]
    }
  }
}

POST/compilations/{id}/auto-edit

Відредагуйте всю добірку за один раз і застосуйте її, заповнюючи лише порожнє: як з'являється кожна сцена (будь-який доступний перехід), текстові картки (слова, шрифт, розмір, положення, час), бібліотечний трек, діапазони швидкості на кліпах зі звичайною швидкістю та смугу прогресу, а також наближення, екранні ефекти, стікери, GIF, емодзі, звукові ефекти й до 2 сцен з реакційними кліпами. direction (необов'язково, до 300 символів) спрямовує все це й зберігається для наступного запуску. Надішліть повернутий take до …/auto-edit/undo, щоб видалити його, або назад сюди як replace_take, щоб замінити його на новий. Платно: compilation; без токенів.

Запит

curl -X POST "$BASE/compilations/10/auto-edit" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"direction": "hype energy, big bold text"}'

Відповідь

{
  "compilation": { "id": 10, "...": "as GET /compilations/{id}" },
  "take": {
    "scene_ids": ["r1"],
    "effect_ids": ["e1", "e2"],
    "sticker_ids": ["g1"],
    "emoji_ids": ["m1"],
    "zoom_ids": ["z1"],
    "sfx_ids": ["s1"],
    "transitions": [{ "scene_id": "2", "kind": "slide", "duration_ms": 400 }],
    "text_cards": [{ "scene_id": "1", "text": "Best of the year" }],
    "music_track_id": "lib-42",
    "speed_ranges": [{ "scene_id": "2", "slot": 0, "start": 24.0, "end": 25.2, "speed": 0.5 }],
    "progress_bar": true
  },
  "counts": { "effects": 2, "stickers": 0, "gifs": 1, "emojis": 1,
              "reaction_clips": 1, "zooms": 1, "sounds": 1, "transitions": 1,
              "texts": 1, "music": 1, "speed_ranges": 1, "progress_bar": 1 }
}

GET/compilations/{id}/audio

Виміряний звук монтажу за його власним годинником: біт музики (або чутного кліпу), гучні моменти, тихі відрізки та спів; onsets=true додає кожен онсет. Кожен звук вимірюється один раз, у фоні, коли його вперше читають або він потрапляє в монтаж — sources показує, які виміряні, а measuring лишається true, доки не виміряні всі. Святкові вогні беруть beat_first, beat_period і beat_clock звідси. Платно: compilation; без токенів.

Запит

curl "$BASE/compilations/10/audio" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "compilation_id": 10,
  "duration_sec": 37.4,
  "measuring": false,
  "sources": [
    { "kind": "music", "status": "measured", "track_id": "lib-42" },
    { "kind": "clip", "status": "measured", "scene_id": "1", "clip_id": 1621 }
  ],
  "beat": [{ "start": 12.0, "end": 37.4, "first_beat": 12.02, "period": 0.38,
             "tempo_bpm": 157.9, "clock": "edit" }],
  "loud": [{ "t": 33.0, "end": 33.4, "over_db": 11.0 }],
  "quiet": [{ "start": 3.4, "end": 9.0, "level_db": -38.0 }],
  "singing": [],
  "onsets": null
}

POST/compilations/{id}/media-scenes

Додайте сцену, яка відтворює файл замість кліпу: реакційний кліп Klipy (klipy) або завантажене відео чи зображення (upload_key). Вона йде після after_scene_id або останньою; into_scene_id робить її ще однією панеллю поруч із кліпами цієї сцени. Завантажене відео враховується в токенах експорту; реакційні кліпи та зображення безкоштовні. Платно: compilation.

Запит

curl -X POST "$BASE/compilations/10/media-scenes" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "klipy": { "source_id": "c3", "slug": "emotional-damage",
             "title": "Emotional Damage", "mp4_url": "https://…" },
  "after_scene_id": "2"
}

POST · PATCH · DELETE/compilations/{id}/narration

Озвучка всього монтажу, транскрибована для субтитрів. POST завантажує її (multipart, поле file) або прикріплює підготовлену за адресою …/narration/from-upload; PATCH встановлює volume та duck; DELETE видаляє її.

Запит

curl -X POST "$BASE/compilations/10/narration/from-upload" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_key": "originals/staging/42/5d8e1a.mp3"}'

Відповідь

{
  "url": "https://clipmaster-media.s3.amazonaws.com/...mp3?...",
  "volume": 1.0,
  "duck": true,
  "duration_sec": 61.4,
  "word_count": 152
}

POST/compilations/{id}/music/suggest

Треки, які підходять до монтажу, кожен з обґрунтуванням. Візьміть один за допомогою POST /music/tracks/{track_id}/select, потім встановіть music.track_id у плані.

Запит

curl -X POST "$BASE/compilations/10/music/suggest" \
  -H "Authorization: Bearer $KEY"

POST/compilations/{id}/{kind}/suggest

Пропозиції для всього монтажу, за його власними секундами: kind – це gifs, stickers або emojis. Надішліть їх на POST …/plan/overlays. Платно: compilation.

Запит

curl -X POST "$BASE/compilations/10/emojis/suggest" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "compilation_id": 10,
  "suggestions": [
    { "emoji": "😂", "timestamp": 14.2, "duration": 1.5, "reason": "The punchline lands" }
  ]
}

POST/compilations/{id}/scenes/{scene_id}/text/suggest

Рядки заголовка та мітки для однієї сцени.

Запит

curl -X POST "$BASE/compilations/10/scenes/1/text/suggest" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "suggestions": [
    { "text": "Day one", "role": "title" }
  ]
}

Планування

Публікуйте кліпи й добірки на підключений канал. Для планування потрібен доступ до функції планування публікацій.

GET/social/accounts

Ваші підключені канали. Спершу підключіть їх у вебзастосунку.

Запит

curl "$BASE/social/accounts" -H "Authorization: Bearer $KEY"

Відповідь

{
  "platforms_available": ["youtube"],
  "accounts": [
    {
      "id": 2,
      "platform": "youtube",
      "account_name": "MyChannel",
      "status": "active"
    }
  ]
}

POST/scheduled-posts

Планує публікацію експорту кліпу чи добірки. Ідемпотентний — повторний запит із тим самим акаунтом, експортом і часом повертає наявний пост.

Запит

curl -X POST "$BASE/scheduled-posts" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Тіло запиту

{
  "social_account_id": 2,
  "clip_id": 456,
  "export_id": 37,
  "scheduled_at": "2026-08-20T16:00:00Z",
  "title": "The pivot that saved us",
  "hashtags": ["startup", "founder"],
  "privacy": "public"
}

Відповідь

{
  "id": 12,
  "clip_id": 456,
  "export_id": 37,
  "social_account_id": 2,
  "platform": "youtube",
  "account_name": "MyChannel",
  "status": "scheduled",
  "scheduled_at": "2026-08-20T16:00:00",
  "title": "The pivot that saved us"
}

GET/scheduled-posts?from_date=&to_date=

Діапазон календаря із запланованими й опублікованими постами.

Запит

curl "$BASE/scheduled-posts?from_date=2026-08-01T00:00:00Z&to_date=2026-08-31T23:59:59Z" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "posts": [
    {
      "id": 12,
      "status": "scheduled",
      "scheduled_at": "2026-08-20T16:00:00",
      "title": "The pivot that saved us"
    }
  ]
}

PATCH · DELETE/scheduled-posts/{id}

Змініть час або відредагуйте публікацію до її публікації (scheduled_at, title, description, hashtags, privacy) або скасуйте її.

Запит

curl -X PATCH "$BASE/scheduled-posts/12" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-08-21T16:00:00Z"}'

POST/scheduled-posts/metadata-suggest

ШІ-заголовок, опис та хештеги з транскрипції кліпу.

Запит

curl -X POST "$BASE/scheduled-posts/metadata-suggest" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"clip_id": 456, "platform": "youtube"}'

Відповідь

{
  "title": "The pivot that saved us",
  "description": "How one decision turned the company around.",
  "hashtags": ["startup", "founder"]
}

DELETE/social/accounts/{id}

Відключити канал. Його історія публікацій, очікувані та опубліковані, видаляється разом з ним.

Запит

curl -X DELETE "$BASE/social/accounts/2" \
  -H "Authorization: Bearer $KEY"

Бібліотека

GET/export/styles

Повертає 15 стилів субтитрів і їхні типові значення.

Запит

curl "$BASE/export/styles" \
  -H "Authorization: Bearer $KEY"

Відповідь

[
  {
    "key": "clean",
    "name": "Clean",
    "category": "social",
    "fontFamily": "Inter",
    "fontSize": 56,
    "color": "#FFFFFF",
    "highlightColor": "#9DC34F"
  }
]

GET/sfx

Бібліотека звукових ефектів; її ідентифікатори використовуються в накладках sfx. Необов’язкова category.

Запит

curl "$BASE/sfx" -H "Authorization: Bearer $KEY"

GET/gifs/search · /gifs/trending

Пошук Klipy або список популярних. kind – це gif, sticker або clip (реакційні кліпи). Розмістіть результат з id як source_id та mp4.url як mp4_url; стікер також потребує image.url як image_url.

Запит

curl "$BASE/gifs/search?q=mind%20blown&kind=sticker&per_page=10" \
  -H "Authorization: Bearer $KEY"

Відповідь

{
  "items": [
    {
      "id": "s9",
      "slug": "mind-blown-sticker",
      "title": "Mind Blown",
      "kind": "sticker",
      "mp4": { "url": "https://….webm", "width": 320, "height": 320 },
      "preview": { "url": "https://….webp", "width": 160, "height": 160 },
      "image": { "url": "https://….webp", "width": 320, "height": 320 }
    }
  ],
  "page": 1,
  "per_page": 10,
  "has_next": true
}

GET/music/search

Пошук фонової музики. Необов’язкові genre, duration_min, duration_max.

Запит

curl "$BASE/music/search?q=upbeat" -H "Authorization: Bearer $KEY"

POST/music/tracks/{track_id}/select

Додайте трек до своєї бібліотеки, щоб добірка могла його використовувати.

Запит

curl -X POST "$BASE/music/tracks/a1b2c3/select" \
  -H "Authorization: Bearer $KEY"

Обліковий запис

GET/billing/balance

Ваш баланс токенів: загальний, зарезервований запущеними завданнями та доступний.

Запит

curl "$BASE/billing/balance" -H "Authorization: Bearer $KEY"

Відповідь

{
  "balance": 120,
  "reserved": 3,
  "available": 117,
  "total_purchased": 200,
  "total_spent": 80
}

GET/billing/usage?period=30

Що ви використали за останні period днів (1–365).

Запит

curl "$BASE/billing/usage?period=30" -H "Authorization: Bearer $KEY"

Відповідь

{
  "period_days": 30,
  "tokens_spent": 42,
  "tokens_purchased": 0,
  "uploads_count": 6,
  "exports_count": 11,
  "minutes_processed": 38.5,
  "minutes_exported": 7.9
}

Помилки

Помилки містять машиночитний код:

{
  "detail": {
    "error": "insufficient_tokens",
    "message": "Not enough tokens for this operation"
  }
}

Загальні коди: api_access_required / session_auth_required (403), subscription_required (403, вказує назву плану feature), insufficient_tokens (402), export_in_progress / export_expired (409). Недійсний або відкликаний ключ повертає 401; перевищення ліміту швидкості повертає 429.

Вартість у токенах

Тарифікується точно так само, як і додаток — 1 токен = 1 вихідна хвилина для обробки завантаження або імпорту з YouTube; експорт тарифікується за правилами додатка (добірка за секундами відтворення вихідного матеріалу); переклад субтитрів кліпу коштує 1 токен. Пропозиції, Автомонтаж, аранжування, аналіз макета, вимірювання аудіо та повторна транскрипція не витрачають токени. Окремого API-білінгу немає.