> ## Documentation Index
> Fetch the complete documentation index at: https://docs.submagic.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Magic Clips

> Automatically generate short-form video clips from YouTube videos

# Create Magic Clips

Generate multiple engaging short-form video clips from YouTube videos automatically. This endpoint processes YouTube videos and creates clips with automatic captions, animations, and effects optimized for social media platforms.

<Note>
  This endpoint requires authentication, Magic Clips subscription, and has a
  rate limit of 500 requests per hour.
</Note>

<Note>
  Magic Clips created via API use your regular Magic Clips credits, not API
  credits. 1 credit per project.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your Submagic API key starting with `sk-`
</ParamField>

## Request Body

<ParamField body="title" type="string" required>
  A descriptive title for your Magic Clips project (1-100 characters)
</ParamField>

<ParamField body="language" type="string" required>
  Language code for captions (2-10 characters, e.g., "en", "es", "fr"). Use the
  [languages endpoint](/api-reference/languages) to get available options.
</ParamField>

<ParamField body="youtubeUrl" type="string" required>
  Valid YouTube video URL to process for clip generation
</ParamField>

<ParamField body="webhookUrl" type="string">
  URL to receive webhook notifications when processing is complete. Must be a
  valid HTTPS URL.
</ParamField>

<ParamField body="templateName" type="string">
  Template to apply for styling. Use the [templates
  endpoint](/api-reference/templates) to get available options. Defaults to
  "Sara" if not specified. Cannot be used together with `userThemeId`.
</ParamField>

<ParamField body="userThemeId" type="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. Cannot be used together with
  `templateName`.
</ParamField>

<ParamField body="minClipLength" type="number">
  Minimum clip duration in seconds (15-300 seconds). Defaults to 15 seconds.
</ParamField>

<ParamField body="maxClipLength" type="number">
  Maximum clip duration in seconds (15-300 seconds). Defaults to 60 seconds.
</ParamField>

<ParamField body="faceTracking" type="boolean">
  Enable face tracking for the generated clips. If not specified, defaults to `true`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the created Magic Clips project (UUID format)
</ResponseField>

<ResponseField name="title" type="string">
  The title you provided for the project
</ResponseField>

<ResponseField name="language" type="string">
  Language code used for captions
</ResponseField>

<ResponseField name="status" type="string">
  Current processing status: `processing`
</ResponseField>

<ResponseField name="webhookUrl" type="string">
  Webhook URL if provided in the request
</ResponseField>

<ResponseField name="templateName" type="string">
  Template name applied to the project
</ResponseField>

<ResponseField name="userThemeId" type="string">
  User theme ID applied to the project
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the project was created
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.submagic.co/v1/projects/magic-clips" \
    -H "x-api-key: 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",
      "templateName": "Hormozi 2",
      "webhookUrl": "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18",
      "minClipLength": 15,
      "maxClipLength": 60,
      "faceTracking": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const createMagicClips = async () => {
    const response = await fetch(
      "https://api.submagic.co/v1/projects/magic-clips",
      {
        method: "POST",
        headers: {
          "x-api-key": "sk-your-api-key-here",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          title: "YT magic-clips test1",
          language: "en",
          youtubeUrl: "https://www.youtube.com/watch?v=eURYVajKLVw",
          templateName: "Hormozi 2",
          webhookUrl: "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18",
          minClipLength: 15,
          maxClipLength: 60,
          faceTracking: true,
        }),
      }
    );

    const project = await response.json();
    console.log("Magic Clips project created:", project.id);
    return project;
  };
  ```

  ```python Python theme={null}
  import requests
  import json

  def create_magic_clips():
      url = 'https://api.submagic.co/v1/projects/magic-clips'
      headers = {
          'x-api-key': 'sk-your-api-key-here',
          'Content-Type': 'application/json'
      }
      data = {
          'title': 'YT magic-clips test1',
          'language': 'en',
          'youtubeUrl': 'https://www.youtube.com/watch?v=eURYVajKLVw',
          'templateName': 'Hormozi 2',
          'webhookUrl': 'https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18',
          'minClipLength': 15,
          'maxClipLength': 60,
          'faceTracking': True
      }

      response = requests.post(url, headers=headers, json=data)
      project = response.json()

      print(f"Magic Clips project created: {project['id']}")
      return project
  ```
</RequestExample>

<ResponseExample>
  ```json 202 Accepted theme={null}
  {
    "id": "e568c322-7fa5-497a-8fb0-3ba32e9e67d2",
    "title": "YT magic-clips test1",
    "language": "en",
    "status": "processing",
    "webhookUrl": "https://webhook-test.com/6704c8535a2a913c3d094aba685d6a18",
    "templateName": "Hormozi 2",
    "userThemeId": "749a19fs-4b45-4b14-bd31-a3970a1a5ff2",
    "createdAt": "2025-09-24T12:55:56.989Z"
  }
  ```
</ResponseExample>

## 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

```json theme={null}
{
  "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,
      "viralityScores": {
        "total": 89,
        "shareability": 23,
        "hook_strength": 22,
        "story_quality": 21,
        "emotional_impact": 23
      },
      "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",
      "directUrl": "https://dqu1p08d61fh.cloudfront.net/api/9cc52d00-43d7-442f-9a22-050312bkm24f/1ddee5b4-101f-4c1e-a74a-b6b3bcfe206c/video.mp4-download.mp4"
    }
  ]
}
```

### Webhook Response Fields

<ResponseField name="projectId" type="string">
  Main project identifier
</ResponseField>

<ResponseField name="status" type="string">
  Processing status: `completed` or `failed`
</ResponseField>

<ResponseField name="title" type="string">
  Project title
</ResponseField>

<ResponseField name="duration" type="number">
  Total duration of the original video in seconds
</ResponseField>

<ResponseField name="completedAt" type="string">
  ISO 8601 timestamp when processing completed
</ResponseField>

<ResponseField name="magicClips" type="array">
  Array of generated clips, each containing: - `id`: Unique clip identifier -
  `title`: AI-generated clip title - `duration`: Clip duration in seconds -
  `viralityScores`: Object containing virality metrics with `total`, `shareability`, `hook_strength`, `story_quality`, and `emotional_impact` scores -
  `status`: Clip processing status - `previewUrl`: URL to preview the clip -
  `downloadUrl`: Direct download URL for the clip - `directUrl`: Direct URL that
  can be embedded on your website or used to play the clip directly
</ResponseField>

## Error Responses

<ResponseField name="400 Bad Request" type="object">
  ```json theme={null}
  {
    "error": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
  ```
</ResponseField>

<ResponseField name="401 Unauthorized" type="object">
  ```json theme={null}
  {
    "error": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseField>

<ResponseField name="403 Forbidden" type="object">
  ```json theme={null}
  {
    "error": "FORBIDDEN",
    "message": "Magic Clips subscription required. Please upgrade your plan or purchase Magic Clips credits."
  }
  ```
</ResponseField>

<ResponseField name="429 Too Many Requests" type="object">
  ```json theme={null}
  {
    "error": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
  ```
</ResponseField>

<ResponseField name="500 Internal Server Error" type="object">
  ```json theme={null}
  {
    "error": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "details": {}
  }
  ```
</ResponseField>