Clip MasterClipMaster

ClipMaster API

ClipMaster को कमांड लाइन, अपनी स्क्रिप्ट या किसी AI असिस्टेंट से ऑटोमेट करें। वही endpoints जो ऐप इस्तेमाल करता है — वही टोकन, कोई अलग बिलिंग नहीं।

सादा टेक्स्ट चाहिए? यह पेज Markdown में पढ़ें — LLM और एजेंट के लिए बना। Claude इस्तेमाल करते हैं? MCP सर्वर कनेक्ट करें — endpoints को हाथ से कॉल करने की ज़रूरत नहीं।

परिचय

API key से ClipMaster को कोड के ज़रिए इस्तेमाल करें। हर endpoint बिल्कुल ऐप जैसा ही काम करता है, और सिर्फ़ आपके अपने प्रोजेक्ट और क्लिप तक सीमित रहता है। API एक्सेस पेड प्लान पर मिलता है।

बेस URL:

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

ऑथेंटिकेशन

ऐप में सेटिंग → API एक्सेस में जाकर key बनाएं। पूरी key (cm_live_…) बनाते समय सिर्फ़ एक बार दिखती है — इसे सुरक्षित रखें। इसे Authorization हेडर में Bearer टोकन की तरह भेजें:

curl https://api.clipmaster.app/api/v1/projects \
  -H "Authorization: Bearer cm_live_xxxxxxxxxxxxxxxxxxxx"
  • सिर्फ़ हेडर में। Key को ?token= क्वेरी पैरामीटर के तौर पर स्वीकार नहीं किया जाता।
  • Key आपके अकाउंट से जुड़ी होती है और आपकी तरह ही काम करती है, सिर्फ़ आपके डेटा तक सीमित।
  • सेटिंग में कभी भी key रिवोक करें; रिवोक की गई key तुरंत काम करना बंद कर देती है।
खाता-प्रबंधन के रूट ऐप में ही रहते हैं। लॉगिन/OAuth, बिलिंग और चेकआउट (आपके टोकन बैलेंस और उपयोग को पढ़ना अनुमत है), एडमिन, API-की प्रबंधन और सोशल चैनल को जोड़ने के लिए एक कुंजी 403 session_auth_required लौटाती है। पहले वेब ऐप में अपना चैनल कनेक्ट करें — बाकी सब स्क्रिप्टेबल है।

कुछ एंडपॉइंट पेड प्लान की सुविधाएँ हैं, जिन्हें नीचे सुविधा के नाम से चिह्नित किया गया है (उदाहरण के लिए compilation)। इसके बिना किसी प्लान पर वे उस feature के साथ 403 subscription_required का जवाब देते हैं।

रेट लिमिट

हर key पर प्रति मिनट 120 रिक्वेस्ट। इससे ज़्यादा होने पर Retry-After हेडर के साथ 429 मिलता है।

AI एंडपॉइंट्स (सुझाव, ऑटो-एडिट, ऑडियो माप, व्यवस्था) की भी अपनी प्रति-उपयोगकर्ता सीमाएँ होती हैं और वे उसी तरह 429 का जवाब देते हैं।

क्विकस्टार्ट

एक YouTube वीडियो इंपोर्ट करें, प्रोसेसिंग का इंतज़ार करें, फिर क्लिप की लिस्ट देखें और डाउनलोड करें। अपने शेल में इन्हें एक बार सेट करें:

KEY="cm_live_xxxxxxxxxxxxxxxxxxxx"
BASE="https://api.clipmaster.app/api/v1"
1URL से वीडियो इंपोर्ट करें

रिक्वेस्ट

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 (स्वचालित, सिमेंटिक या 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। कुछ देर के लिए वैलिड अपलोड टारगेट लौटाता है: लौटाए गए upload.fields को बिना बदले फ़ाइल को upload.url पर POST करें, फिर 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 करें, फिर फ़ाइल को अंतिम रूप से, 15 मिनट के भीतर upload.url पर, फिर asset_key का उपयोग /users/me/logo/from-upload, /projects/{id}/clips/{clip_id}/logo/from-upload, /compilations/{id}/narration/from-upload या /compilations/{id}/media-scenes (as 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 चल रहा है, पूरा हो गया है, विफल हो गया है, बासी है (30 मिनट से अधिक समय से चल रहा है, इसलिए यह शायद मर गया है — इसे पुनरारंभ करने से पहले फिर से जांचें) या शून्य (कभी नहीं चला), 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, ज़ूम, screenEffects, फ़्रेमिंग, लोगो, प्रोग्रेस बार, ओरिएंटेशन, 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 शून्य हो। पुराने पंच और धीमी ज़ूम परिवर्तित होते हैं।

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 के लिए क्लिप को पोल करें, या analyses.layout.status के लिए GET …/analysis को पोल करें; हर फ्रेम उसका 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

प्रति-क्लिप लोगो अपलोड करें (मल्टीपार्ट, फ़ील्ड 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 सुझाव और ऑटो-एडिट

सुझाव केवल पढ़ने के लिए हैं: वे दर्शक के समय पर प्लेसमेंट लौटाते हैं, जैसा कि वे आए थे, 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}, GET …/analysis का auto_edit अनुभाग भी) है। कुछ भी लागू नहीं किया गया है: इसके हिस्सों को 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

AI के साथ संकलन को दृश्यों की एक नई योजना में फिर से काटें। format: कस्टम (एक मोंटाज; 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 ऑडियो होता है। संक्रमण: कट, फेड, स्लाइड, वाइप। छोड़े गए ओवरले रखे जाते हैं; छोड़ा गया 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) या एक अपलोड किया गया वीडियो या छवि (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 इसे अपलोड करता है (मल्टीपार्ट, फ़ील्ड 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

क्लिप या कंपाइलेशन एक्सपोर्ट को पब्लिश के लिए शेड्यूल करें। Idempotent — उसी अकाउंट, एक्सपोर्ट और समय के साथ दोबारा भेजने पर मौजूदा पोस्ट ही लौटती है।

रिक्वेस्ट

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

क्लिपी खोजें, या ट्रेंडिंग क्या है उसे सूचीबद्ध करें। 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 टोकन = अपलोड या YouTube आयात को संसाधित करने के लिए 1 स्रोत मिनट; निर्यात ऐप के नियमों के अनुसार शुल्क लेते हैं (एक संकलन उसके चलने वाले स्रोत सेकंड के अनुसार); एक क्लिप कैप्शन अनुवाद की लागत 1 टोकन है। सुझाव, ऑटो-एडिट, व्यवस्था, लेआउट विश्लेषण, ऑडियो माप और फिर से ट्रांसक्राइब करने में कोई टोकन खर्च नहीं होता है। कोई अलग API बिलिंग नहीं है।