Create Short

POST /shorts/create

Creates a new video short from a YouTube URL or uploaded file URL. The AI analyzes your video content, identifies the most engaging segments, and generates short-form clips with captions, overlays, and effects based on your configuration.

Each request consumes 1 credit regardless of how many clips are generated.

Request body

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "start": 0,
  "end": 600,
  "preferredLength": "under60sec",
  "language": "en",
  "templateId": "660b8531aedb346bbe26eb43",
  "music": true,
  "musicName": "Energetic Beat",
  "musicVolume": 15,
  "layout": "auto"
}

Video source parameters

You must provide exactly one of the following — not both.

Providing both url and fileUrl in the same request will return a 400 error.

YouTube URL — Provide a standard YouTube video URL. The API downloads and processes the video automatically. YouTube Shorts URLs (/shorts/) are not supported.

File URL — Provide a publicly accessible URL pointing to a video file. The API fetches the file directly. Useful for videos hosted on S3, GCS, Azure Blob, or any CDN.

Time range parameters

The start and end parameters define the segment of the source video to analyze. The AI clips within this time range.

Constraints:

• Minimum time window: 1 second. If end - start < 1, the request is rejected with a 400 error.
• Maximum time window: 1,200 seconds (20 minutes). If end - start > 1200, the request is rejected with a 400 error.
• Maximum video duration: 18,000 seconds (5 hours). Videos exceeding this are rejected.
• If the specified range exceeds the actual video duration, the range is automatically adjusted. The response will include a timeAdjustment object showing the original and adjusted values.

{
  "start": 0,
  "end": 600
}

This tells the AI to analyze the first 10 minutes of the video and find the best clips within that range.

Content parameters

Preferred length options

The preferredLength parameter controls the target duration of each generated clip. The AI uses this as a guideline — actual clip lengths may vary slightly based on content.

No clipping mode

When noClipping is set to true, the AI skips segment detection and processes the entire start to end range as a single clip. This is useful when you already know the exact segment you want and just need captions, effects, and formatting applied.

{
  "url": "https://www.youtube.com/watch?v=...",
  "start": 120,
  "end": 180,
  "noClipping": true,
  "language": "en"
}

Overlay parameters

These parameters add visual elements to your generated shorts. Each overlay type can be enabled independently.

Meme hooks

Meme hooks are short, attention-grabbing clips (typically 2–5 seconds) prepended to the start of your shorts. They help increase view retention by immediately capturing the viewer's attention.

{
  "memeHook": true,
  "memeHookName": "Wait For It"
}

Browse available meme hooks with GET /meme-hooks. If memeHookName is omitted, a random hook is selected.

Game video overlays

Game video overlays create a split-screen effect with your main content on top and gameplay footage on the bottom. This is a popular format on TikTok for increasing watch time.

{
  "gameVideo": true,
  "gameVideoName": "Minecraft Parkour"
}

Browse available game videos with GET /game-videos. If gameVideoName is omitted, a random video is selected.

Call-to-action

The CTA overlay adds a text banner at the end of the clip. Useful for directing viewers to your website, channel, or product.

{
  "ctaEnabled": true,
  "ctaText": "Subscribe for more!"
}

Music parameters

Background music is mixed with the original video audio. The musicVolume parameter controls the relative loudness of the music compared to the original audio — lower values keep the music subtle, higher values make it more prominent.

{
  "music": true,
  "musicName": "Chill Lofi",
  "musicVolume": 20
}

Browse available music tracks with GET /music. If musicName is omitted, a random track is selected.

Volume guidelines:

• 5–15 — Subtle background ambiance, good for dialogue-heavy content
• 15–30 — Balanced mix, noticeable but doesn't overpower speech
• 30–50 — Prominent music, suitable for montage-style clips
• 50+ — Music-forward, best when the original audio isn't important

Layout parameter

The layout parameter determines how the source video (typically horizontal/landscape) is reframed for vertical short-form output (1080x1920).

When to use each layout:

• auto — Best default choice. The AI analyzes the video and picks the optimal framing.
• fill — Use for talking-head videos, interviews, or content where the main subject is centered.
• fit — Use for screen recordings, presentations, or content where all edges matter.
• square — Use specifically for Instagram feed or other platforms that favor square content.

Supported languages

The language parameter accepts ISO 639-1 language codes. This controls the transcription and caption language.

Example request

curl -X POST https://aiclipping.ssemble.com/api/v1/shorts/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_ssemble_your_key" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "start": 0,
    "end": 600,
    "preferredLength": "under60sec",
    "language": "en",
    "music": true,
    "musicVolume": 15,
    "layout": "auto"
  }'

Example with all overlays

curl -X POST https://aiclipping.ssemble.com/api/v1/shorts/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_ssemble_your_key" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "start": 0,
    "end": 600,
    "preferredLength": "under60sec",
    "language": "en",
    "templateId": "660b8531aedb346bbe26eb43",
    "music": true,
    "musicName": "Energetic Beat",
    "musicVolume": 20,
    "memeHook": true,
    "memeHookName": "Wait For It",
    "hookTitle": true,
    "ctaEnabled": true,
    "ctaText": "Subscribe for more!",
    "layout": "fill"
  }'

Response

{
  "data": {
    "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "processing",
    "creditsUsed": 1,
    "estimatedCompletionTime": "2024-06-01T12:30:00.000Z",
    "queuePosition": null
  }
}

Response fields

Time adjustment response

If the requested time range exceeds the video duration, the API automatically adjusts it and returns details in the response:

{
  "data": {
    "requestId": "...",
    "status": "processing",
    "creditsUsed": 1,
    "estimatedCompletionTime": "...",
    "queuePosition": null,
    "timeAdjustment": {
      "message": "Time range was automatically adjusted to fit within video duration",
      "original": { "start": 0, "end": 9999 },
      "adjusted": { "start": 0, "end": 3600 },
      "videoDuration": 3600
    }
  }
}

Error responses

Important notes

• Each request consumes 1 credit regardless of the number of clips generated.
• The time window (end - start) must be between 1 second and 1,200 seconds (20 minutes). Requests outside this range are rejected with a 400 error.
• YouTube Shorts URLs (youtube.com/shorts/...) are not supported — use the full video URL instead.
• Maximum video duration is 5 hours (18,000 seconds).
• Processing typically takes 5–30 minutes depending on video length and queue position.
• After creating a request, poll GET /shorts/:id/status every 10 seconds until completion.