POST
/
v1
/
projects
/
magic-clips
curl -X POST "https://api.submagic.co/v1/projects/magic-clips" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "YT magic-clips test1",
    "language": "en",
    "youtubeUrl": "https://www.youtube.com/watch?v=eURYVajKLVw",
    "webhookUrl": "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18",
    "minClipLength": 15,
    "maxClipLength": 60
  }'

{
  "id": "e568c322-7fa5-497a-8fb0-3ba32e9e67d2",
  "title": "YT magic-clips test1",
  "language": "en",
  "status": "processing",
  "webhookUrl": "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18",
  "createdAt": "2025-09-24T12:55:56.989Z"
}

​
Create Magic Clips

Generate multiple engaging short-form video clips from YouTube videos automatically using AI. This endpoint processes YouTube videos and creates clips with automatic captions, animations, and effects optimized for social media platforms.
This endpoint requires authentication, Magic Clips subscription, and has a rate limit of 500 requests per hour.
Magic Clips created via API use your regular Magic Clips credits, not API credits.

​
Authentication

​
Authorization
string
required
Your Submagic API key in Bearer token format: Bearer sk-your-api-key-here

​
Request Body

​
title
string
required
A descriptive title for your Magic Clips project (1-100 characters)
​
language
string
required
Language code for captions (2-10 characters, e.g., “en”, “es”, “fr”). Use the languages endpoint to get available options.
​
youtubeUrl
string
required
Valid YouTube video URL to process for clip generation
​
webhookUrl
string
URL to receive webhook notifications when processing is complete. Must be a valid HTTPS URL.
​
userThemeId
string
ID of a custom user theme to apply for styling. Must be a valid UUID of a theme that belongs to you or your team.
​
minClipLength
number
Minimum clip duration in seconds (15-300 seconds). Defaults to 15 seconds.
​
maxClipLength
number
Maximum clip duration in seconds (15-300 seconds). Defaults to 60 seconds.

​
Response

​
id
string
Unique identifier for the created Magic Clips project (UUID format)
​
title
string
The title you provided for the project
​
language
string
Language code used for captions
​
status
string
Current processing status: processing
​
webhookUrl
string
Webhook URL if provided in the request
​
createdAt
string
ISO 8601 timestamp when the project was created
curl -X POST "https://api.submagic.co/v1/projects/magic-clips" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "YT magic-clips test1",
    "language": "en",
    "youtubeUrl": "https://www.youtube.com/watch?v=eURYVajKLVw",
    "webhookUrl": "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18",
    "minClipLength": 15,
    "maxClipLength": 60
  }'

{
  "id": "e568c322-7fa5-497a-8fb0-3ba32e9e67d2",
  "title": "YT magic-clips test1",
  "language": "en",
  "status": "processing",
  "webhookUrl": "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18",
  "createdAt": "2025-09-24T12:55:56.989Z"
}

​
Webhook Integration

When processing is complete, a webhook notification will be sent to the provided webhookUrl (if specified). The webhook payload includes information about the main project and all generated clips.

​
Webhook Payload Structure

{
  "projectId": "e568c322-7fa5-497a-8fb0-3ba32e9e67d2",
  "status": "completed",
  "title": "YT magic-clips test1",
  "duration": 283,
  "completedAt": "2025-09-24T12:59:24.880Z",
  "magicClips": [
    {
      "id": "364fe092-b68d-468a-9558-bfca7c4d190e",
      "title": "ProMotion Display Breakthrough",
      "duration": 21.04,
      "status": "completed",
      "previewUrl": "https://app.submagic.co/view/364fe092-b68d-468a-9558-bfca7c4d190g",
      "downloadUrl": "https://app.submagic.co/api/file/download?path=3c6cd7cd-3f5e-4def-b662-69c48a7fc8ce/e568c322-7fa5-497a-8fb0-3ba32e9e67d2/364fe092-b68d-468a-9558-bfca7c4d130e-download.mp4&newFileName=ProMotion%20Display%20Breakthrough.mp4"
    }
  ]
}

​
Webhook Response Fields

​
projectId
string
Main project identifier
​
status
string
Processing status: completed or failed
​
title
string
Project title
​
duration
number
Total duration of the original video in seconds
​
completedAt
string
ISO 8601 timestamp when processing completed
​
magicClips
array
Array of generated clips, each containing: - id: Unique clip identifier - title: AI-generated clip title - duration: Clip duration in seconds - status: Clip processing status - previewUrl: URL to preview the clip - downloadUrl: Direct download URL for the clip

​
Error Responses

​
400 Bad Request
object
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters"
}
​
401 Unauthorized
object
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
​
403 Forbidden
object
{
  "error": "FORBIDDEN",
  "message": "Magic Clips subscription required"
}
​
429 Too Many Requests
object
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 60
}
​
500 Internal Server Error
object
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred",
  "details": {}
}