ClipMaster API

Автоматизирайте ClipMaster от командния ред, от собствени скриптове или от AI асистент. Същите endpoint-и, които ползва приложението — таксувани със същите токени, без отделно плащане.

Предпочитате чист текст? Прочетете страницата като Markdown — направено за LLM модели и агенти. Ползвате Claude? Свържете MCP сървъра вместо да викате endpoint-ите ръчно.

Общ преглед

Достъпвайте ClipMaster програмно с API ключ. Всеки endpoint работи точно както в приложението и има достъп само до вашите проекти и клипове. Достъпът до 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"

Само в хедъра. Ключовете не се приемат като query параметър ?token=.
Ключът е свързан с акаунта ви и действа от ваше име, само върху вашите данни.
Можете да анулирате ключ по всяко време от Настройки; анулираният ключ спира да работи веднага.

Маршрутите за управление на акаунт остават в приложението. Ключ връща 403 session_auth_required за вход/OAuth, таксуване и плащане (четенето на баланса и употребата на токени е разрешено), администратор, управление на API ключове и свързване на социален канал. Първо свържете канала си в уеб приложението — всичко останало е скриптуемо.

Някои крайни точки са функции на платен план, отбелязани по-долу с името на функцията (например compilation). При план без нея те отговарят 403 subscription_required с тази feature.

Лимити на заявките

120 заявки на минута за ключ. При превишаване получавате 429 с хедър Retry-After.

AI крайните точки (предложения, Автоматична редакция, измерване на аудио, подреждане) също имат свои собствени лимити за потребител и отговарят 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

Импортирайте YouTube URL. Обработката започва незабавно; проверявайте статуса на върнатия проект. Платено: 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

Списък на създадените клипове с AI метаданни (кукичка, тип клип, увереност).

Заявка

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}

Пълни детайли за един клип — надмножество на елемента от списъка: всяко поле на функция, AI анализ на сцената, нейното запълване, значка и виралност. Всеки кадър, аудиото и думите са в 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 (вярно: стъпката на AI сцената е неуспешна и това е неоценен резервен вариант с фиксирана дължина). 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), sfx, зуум, екранни ефекти, кадриране, лого, лента за напредък, ориентация, 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. По-старите punch и slow зуум ефекти се конвертират.

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. Преобразуването на времето на редактора и настройките по подразбиране се прилагат за вас, а AI предложенията могат да бъдат изпратени такива, каквито са. Добавя само.

Заявка

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"}'

AI предложения и Auto-edit

Предложенията са само за четене: те връщат разположения във времето на зрителя, готови за изпращане до 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

Рендерира клип със запазените му настройки. Връща 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

Пренарежете компилацията с AI в нов план от сцени. 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 означава, че стъпката на AI е неуспешна и клиповете са запазени в ред.

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

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

Заявка

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

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

Пренарежете една сцена с AI, оставяйки останалите. По избор 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

AI заглавие, описание и хаштагове от транскрипция на клип.

Заявка

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 таксуване.