Get Shorts

`GET /shorts/:id`

Returns the full details of a completed request including all generated short clips with video URLs, AI-generated metadata, and processing information.

Path parameters

Parameter	Type	Description
`id`	string	The request ID returned from `POST /shorts/create`. Must be a valid 24-character hex string.

Request

curl -H "X-API-Key: sk_ssemble_your_key" \
  https://aiclipping.ssemble.com/api/v1/shorts/665a1b2c3d4e5f6a7b8c9d0e

Response

{
  "data": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "completed",
    "progress": 100,
    "userEmail": "user@example.com",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "start": 0,
    "end": 600,
    "title": "My Video Title",
    "language": "en",
    "template": "hormozi1",
    "captionLanguage": "",
    "heatmap": [],
    "sentences": [
      {
        "index": 0,
        "sentence": "This is the first transcribed sentence.",
        "start": 12.5,
        "end": 15.3
      },
      {
        "index": 1,
        "sentence": "This is the second transcribed sentence with more content.",
        "start": 15.3,
        "end": 22.8
      }
    ],
    "preferredLength": "under60sec",
    "projectId": null,
    "shorts": [
      {
        "id": "f2c713ff-865f-4cd5-98ab-f6aa696a3620",
        "title": "The Most Viral Moment",
        "sentenceIndexes": [0, 1],
        "reason": "High engagement potential due to emotional hook and surprise element",
        "description": "Speaker reveals an unexpected insight about productivity that challenges conventional wisdom. #productivity #mindset #viral",
        "viral_score": 85,
        "video_url": "https://cf.ssemble.com/ssemble-shortsmaker-plugin/export/file_example.mp4",
        "startTimestamp": 12.5,
        "endTimestamp": 55.3,
        "duration": 43,
        "width": 1080,
        "height": 1920,
        "recompiling": false,
        "error": false
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "Key Takeaway That Changes Everything",
        "sentenceIndexes": [3, 4, 5],
        "reason": "Actionable advice with strong shareability — viewers will want to save this",
        "description": "A concise summary of the three-step framework discussed earlier in the video. #tips #howto #learning",
        "viral_score": 72,
        "video_url": "https://cf.ssemble.com/ssemble-shortsmaker-plugin/export/file_example2.mp4",
        "startTimestamp": 120.0,
        "endTimestamp": 175.5,
        "duration": 55,
        "width": 1080,
        "height": 1920,
        "recompiling": false,
        "error": false
      }
    ]
  }
}

Request-level fields

Field	Type	Description
`_id`	string	The request ID
`status`	string	Processing status (`completed`, `failed`, etc.)
`progress`	number	Processing progress (0–100)
`userEmail`	string	Email of the user who created the request
`url`	string	Original source video URL
`start`	number	Start time that was processed (seconds)
`end`	number	End time that was processed (seconds)
`title`	string	Title of the source video
`language`	string	Language used for transcription
`template`	string	Caption template name that was applied
`captionLanguage`	string	Caption language (empty string if same as `language`)
`heatmap`	array	Engagement heatmap data for the source video (may be empty)
`sentences`	array	Full transcription broken into sentences (see Sentence object below)
`preferredLength`	string	Preferred clip length setting used
`projectId`	string \| null	Associated project ID, or `null` if not linked to a project

Sentence object

Each item in the sentences array represents one transcribed sentence from the source video:

Field	Type	Description
`index`	number	Zero-based index of the sentence in the transcription
`sentence`	string	The transcribed text
`start`	number	Start time of the sentence in the source video (seconds)
`end`	number	End time of the sentence in the source video (seconds)

Short object fields

Each item in the shorts array represents one generated clip:

Field	Type	Description
`id`	string	Unique clip identifier (UUID)
`title`	string	AI-generated title optimized for social media engagement
`sentenceIndexes`	number[]	Array of sentence indexes (from the `sentences` array) that this clip contains
`reason`	string	AI explanation of why this segment was selected as a good clip
`description`	string	AI-generated social media caption with hashtags, ready to use when posting
`viral_score`	number	AI-predicted virality score from 0 (low potential) to 100 (high potential)
`video_url`	string	URL to download the rendered video file
`startTimestamp`	number	Start position in the source video (seconds)
`endTimestamp`	number	End position in the source video (seconds)
`duration`	number	Duration of the generated clip (seconds)
`width`	number	Video width in pixels (default: 1080)
`height`	number	Video height in pixels (default: 1920)
`recompiling`	boolean	`true` if the clip is currently being re-rendered
`error`	boolean	`true` if an error occurred rendering this specific clip
`errorMessage`	string	Only present when `error` is `true`. Describes what went wrong with this specific clip.

Understanding the viral score

The viral_score is an AI-generated prediction of how well the clip might perform on social media, based on:

Content engagement — Does the segment contain a hook, surprise, or emotional moment?
Pacing and delivery — Is the speaking pace engaging? Are there natural pauses?
Completeness — Does the clip tell a complete micro-story or deliver a full insight?
Shareability — Would viewers want to share, save, or comment on this clip?

Score range	Meaning
80–100	Excellent — strong viral potential with clear hooks and engagement drivers
60–79	Good — solid content that should perform well on most platforms
40–59	Average — decent content but may lack a strong hook or payoff
0–39	Below average — may work as supplementary content

Use the viral score to prioritize which clips to publish first. Clips with higher scores tend to generate more engagement.

Video URL handling

Video URLs point to rendered MP4 files hosted on cloud storage.

Important considerations:

Temporary URLs — Video URLs are temporary and will expire. Download videos promptly after retrieval.
File format — All videos are rendered as MP4 (H.264) files.
Dimensions — Default output is 1080x1920 (vertical 9:16). The width and height fields confirm the actual dimensions.
Download the files — Don't rely on the URLs for long-term storage. Download and host the files yourself.

Downloading videos

async function downloadShorts(requestId, apiKey) {
  const res = await fetch(
    `https://aiclipping.ssemble.com/api/v1/shorts/${requestId}`,
    { headers: { 'X-API-Key': apiKey } }
  );
  const { data } = await res.json();
 
  for (const short of data.shorts) {
    if (short.error) {
      console.log(`Clip ${short.id} had an error: ${short.errorMessage}`);
      continue;
    }
 
    const videoRes = await fetch(short.video_url);
    const buffer = await videoRes.arrayBuffer();
 
    // Save to file (Node.js)
    const fs = await import('fs/promises');
    await fs.writeFile(`short-${short.id}.mp4`, Buffer.from(buffer));
    console.log(`Downloaded: short-${short.id}.mp4 (${short.duration}s, score: ${short.viral_score})`);
  }
}

Error responses

Status	Code	When
400	`invalid_request`	Invalid request ID format
401	`invalid_api_key`	Missing or invalid API key
404	`resource_not_found`	Request not found or does not belong to your account

Important notes

Wait for completion — Call this endpoint only after GET /shorts/:id/status returns status: "completed". If called before completion, the shorts array may be empty or incomplete.
Multiple clips — A single request typically generates multiple clips. The number depends on the time range, preferred length, and available content.
Partial errors — Individual clips may fail (error: true) even if the overall request succeeded. Always check the error field on each clip.
Recompiling — If recompiling is true, the clip is being re-rendered. Wait a few minutes and retry.

On this page