Create clip

POST/api/v1/clips

Cuts short vertical clips out of a YouTube video. The AI picks the moments inside the start_time to end_time range, then renders clip_count clips with the framing and subtitle settings you pass.

Authorization

MagerApiKey

x-mager-api-key<token>

Mager API key

In: header

Header Parameters

x-mager-api-key*string

Mager API key

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

callback_url?string

Optional webhook URL called when the task reaches finished or failed. Deliveries are signed exactly like generation task webhooks.

Formaturi

Lengthlength <= 2048

category?string

Lengthlength <= 120

clip_count?integer

How many clips to cut from the selected range.

Range1 <= value <= 20

Default1

clip_length?string

Target clip duration range, for example 30-90s.

Default"30-90s"

end_time*string

Timestamp in HH:MM:SS.

Match^\d{2}:\d{2}:\d{2}$

idempotency_key?string

Optional client-generated key that makes this call safe to retry. A repeat call with the same key returns the original task instead of running and charging again.

Length1 <= length <= 255

start_time*string

Timestamp in HH:MM:SS.

Match^\d{2}:\d{2}:\d{2}$

subtitle?

Default{}

target_resolution?string

Output resolution. Capped by the account tier.

Default"720p"

Value in

"480p"
"720p"
"1080p"

user_prompt?string

Extra editorial direction for the clip selection.

Lengthlength <= 2000

video_description?string

Lengthlength <= 5000

video_duration_seconds*integer

Total duration of the source video in seconds.

Range0 < value

video_thumbnail_url?string

Formaturi

video_title?string

Source video title. Used for naming and analysis context.

Lengthlength <= 500

video_url*string

YouTube URL of the source video.

Formaturi

watermark?boolean

Defaulttrue

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/clips" \  -H "x-mager-api-key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",    "start_time": "00:00:00",    "end_time": "00:20:00",    "clip_count": 3,    "clip_length": "30-90s",    "target_resolution": "1080p",    "user_prompt": "Prefer moments with a strong opening line",    "video_title": "How we grew to 10k users",    "video_duration_seconds": 3120,    "subtitle": {      "with_subtitle": true,      "font_style": "eridu",      "font_size": 48,      "max_words_on_screen": 3,      "allowed_editing_styles": [        "STATIC_CROP",        "DYNAMIC_CROP"      ]    },    "callback_url": "https://client.example.com/webhooks/mager"  }'

{  "status": 201,  "message": "Success",  "data": {    "task_id": "cmclip01hxyz123",    "status": "running",    "model": null,    "template_id": null,    "callback_url": "https://client.example.com/webhooks/mager",    "created_at": "2026-08-14T06:00:00.000Z",    "updated_at": "2026-08-14T06:00:00.000Z",    "completed_at": null,    "error": null,    "billing": {      "base_moods": 1,      "charged_moods": 2,      "extra_moods_charged": 2    },    "output": null,    "result": [],    "webhooks": []  }}

Authorization

Header Parameters

Request Body

Response Body

201application/json

401application/json

404application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`