Create Project

Create a new video project by providing a video URL. This endpoint will download the video, transcribe the audio, and apply the specified template with AI-generated captions and effects.

This endpoint requires authentication and has a rate limit of 500 requests per hour.

Authentication

x-api-key

string

required

Your Submagic API key starting with sk-

Request Body

title

string

required

A descriptive title for your video project (1-100 characters)

language

string

required

Language code for transcription (e.g., “en”, “es”, “fr”). Use the languages endpoint to get available options.

videoUrl

string

required

Public URL to your video file. Must be accessible without authentication and in a supported format.

aiEditTemplate

string

Name of an AI edit template to apply. AI edit templates automatically apply AI-powered scene splitting, B-roll, music, and styling to your video. Available templates: "kelly" (minimal, design), "karl" (effective, modern), "ella" (dynamic, bold).When aiEditTemplate is provided, the only other fields you can pass alongside it are title, language, videoUrl, webhookUrl, and dictionary. All other fields will be ignored or rejected.

presetId

string

ID of a saved preset to apply to the project. A preset is a snapshot of your project settings — including captions style, hook title, music, effects, and more. When provided, all preset settings are automatically applied after transcription completes. To get your preset ID, go to the Presets page in the app, open the dropdown menu on any preset card, and click “Copy ID”.Cannot be combined with templateName, userThemeId, hookTitle, music, items, magicZooms, magicBrolls, magicBrollsPercentage, removeSilencePace, or removeBadTakes — the preset already controls these settings.

templateName

string

Template to apply for styling. Use the templates endpoint to get available options. Defaults to “Sara” if not specified. Cannot be used together with userThemeId.

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. Cannot be used together with templateName. You can find the id of your custom theme by opening a project, selecting the theme, pressing the pen icon to edit it. You’ll see the id of the theme under theme’s name.

hookTitle

boolean | object

Adds an animated opening caption (hook) to the video. Set to true to let AI generate using the default style or pass an object to customize the appearance:

text (optional): Custom hook, 1-100 characters
template (optional): Hook title template name. Defaults to "tiktok". Use the hook title templates endpoint to retrieve valid options.
top (optional): Vertical position (0-80). Defaults to 50.
size (optional): Font size (0-80). Defaults to 30.

webhookUrl

string

URL to receive webhook notifications when processing is complete. Must be a valid HTTPS URL.

dictionary

array

Array of custom words or phrases to improve transcription accuracy (max 100 items, 50 characters each).

items

array

Optional array of items to insert into the video. Each item must include a type field to specify whether it’s user media from your library or AI-generated content.

Hide User Media Item

type

string

required

Must be set to "user-media"

startTime

number

required

Start time in seconds where the media should begin (must be ≥ 0)

endTime

number

required

End time in seconds where the media should end (must be greater than startTime)

userMediaId

string

required

UUID of the user media from your library. You can find this ID in the editor’s ‘B-roll’ tab → ‘My videos’ section under each video.

layout

string

Layout mode for the inserted media. Available values depend on the media type:Video media: "cover", "contain", "rounded", "square", "split-50-50", "split-35-65", "split-50-50-bordered", "split-35-65-bordered", "pip-top-right", "pip-bottom-right"Image media: "cover", "contain", "rounded", "square"

Hide AI B-roll Item

type

string

required

Must be set to "ai-broll"

startTime

number

required

Start timestamp in seconds (must be ≥ 0)

endTime

number

required

End timestamp in seconds. Must be greater than startTime and no more than 12 seconds later.

prompt

string

required

Describes what the AI B-roll should depict (1-2500 characters)

layout

string

Layout mode for the AI B-roll. Allowed values: "cover", "contain", "rounded", "square", "split-50-50", "split-35-65", "split-50-50-bordered", "split-35-65-bordered", "pip-top-right", "pip-bottom-right"

Important: Each item must have a type field. Items cannot overlap with each other in time. Requests that include invalid durations, overlapping ranges, or prompts outside the allowed length will be rejected.

magicZooms

boolean

Enable automatic zoom effects on the video to enhance visual engagement. Optional, defaults to false.

magicBrolls

boolean

Enable automatic B-roll insertion to enhance video content with relevant supplementary footage. Optional, defaults to false.

magicBrollsPercentage

number

Percentage of automatic B-rolls to include in the video (0-100). Only effective when magicBrolls is enabled. Optional, defaults to 50.

removeSilencePace

string

Automatically remove silence from the video at the specified pace. Optional. Allowed values: natural, fast, extra-fast. - extra-fast: 0.1-0.2 seconds of silence removal - fast: 0.2-0.6 seconds of silence removal - natural: 0.6+ seconds of silence removal

removeBadTakes

boolean

Automatically detect and remove bad takes and silence from the video using AI analysis. Optional, defaults to false.

cleanAudio

boolean

Enable AI-powered audio cleanup that removes background noises from the video. Optional, defaults to false.

disableCaptions

boolean

Hide captions from the exported video. Optional, defaults to false.

music

object

Optional background music track that spans the full project duration. The referenced media must be an AUDIO type file in your user media library.

Hide Music Object

userMediaId

string

required

UUID of an audio file from your media library. Must reference a user media item with type AUDIO. Use the List User Media endpoint to find available audio files.

volume

number

required

Playback volume (1-100)

startFromTime

number

Start offset within the audio file in seconds. Defaults to 0.

fade

boolean

Apply a fade-in/fade-out effect to the music track. Defaults to true.

Supported Formats & Limits

Supported Formats

MP4 (.mp4) - MOV (.mov)

File Limits

Max size: 2GB - Max duration: 2 hours

Response

string

Unique identifier for the created project (UUID format)

title

string

The title you provided for the project

language

string

Language code used for transcription

status

string

Current processing status: processing, transcribing, exporting, completed, or failed

webhookUrl

string

Webhook URL if provided in the request

templateName

string

Template name applied to the project

userThemeId

string

User theme ID applied to the project

presetId

string

Preset ID applied to the project

aiEditTemplate

string

AI edit template applied to the project (if any): kelly, karl, or ella

magicZooms

boolean

Whether automatic zoom effects are enabled for the video

magicBrolls

boolean

Whether automatic B-roll insertion is enabled for the video

magicBrollsPercentage

number

Percentage of automatic B-rolls to include in the video (0-100)

removeSilencePace

string

Pace setting for automatic silence removal: natural, fast, or extra-fast

removeBadTakes

boolean

Whether automatic bad takes and silence removal is enabled

cleanAudio

boolean

Whether AI-powered audio cleanup is enabled

createdAt

string

ISO 8601 timestamp when the project was created

updatedAt

string

ISO 8601 timestamp when the project was last updated

curl -X POST "https://api.submagic.co/v1/projects" \
  -H "x-api-key: sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Awesome Video",
    "language": "en",
    "videoUrl": "https://example.com/videos/sample.mp4",
    "templateName": "Hormozi 2",
    "items": [
      {
        "type": "user-media",
        "startTime": 5,
        "endTime": 10,
        "userMediaId": "123e4567-e89b-12d3-a456-426614174000",
        "layout": "pip-top-right"
      },
      {
        "type": "ai-broll",
        "startTime": 15,
        "endTime": 21,
        "prompt": "person performing multiple back exercises on gym equipment",
        "layout": "split-50-50"
      }
    ],
    "webhookUrl": "https://yoursite.com/webhook/submagic",
    "dictionary": ["Submagic", "AI-powered", "captions"],
    "magicZooms": true,
    "magicBrolls": true,
    "magicBrollsPercentage": 75,
    "removeSilencePace": "fast",
    "removeBadTakes": true,
    "cleanAudio": true,
    "hookTitle": {
      "text": "Stop scrolling—watch this in 30 seconds",
      "template": "tiktok",
      "top": 45,
      "size": 32
    },
    "music": {
      "userMediaId": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
      "volume": 30,
      "startFromTime": 0,
      "fade": true
    }
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "My Awesome Video",
  "language": "en",
  "status": "processing",
  "webhookUrl": "https://yoursite.com/webhook/submagic",
  "templateName": "Hormozi 2",
  "magicZooms": true,
  "magicBrolls": true,
  "magicBrollsPercentage": 75,
  "removeSilencePace": "fast",
  "removeBadTakes": true,
  "cleanAudio": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Custom Dictionary

Improve transcription accuracy by providing custom terms:

{
  "dictionary": [
    "Submagic",
    "API endpoint",
    "captions",
    "transcription",
    "AI-powered",
    "webhook notification"
  ]
}

Best practices for dictionary terms:

Include brand names, product names, or technical terms
Add words that are frequently mispronounced or misunderstood
Keep terms under 50 characters each
Limit to 100 terms per project

Webhook Integration

Receive notifications when your project is complete:

{
  "webhookUrl": "https://yoursite.com/webhook/submagic"
}

Your webhook endpoint will receive a POST request:

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "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",
  "timestamp": "2024-01-15T10:45:00.000Z"
}

Error Responses

400 Validation Error

object

{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "videoUrl",
      "message": "Must be a valid URL",
      "value": "invalid-url"
    }
  ]
}

400 Preset Conflict

object

{
  "error": "VALIDATION_ERROR",
  "message": "presetId cannot be combined with templateName, userThemeId, magicZooms, magicBrolls, magicBrollsPercentage, removeBadTakes, removeSilencePace, items, hookTitle, or music. The preset controls these settings."
}

400 Invalid Hook Title Template

object

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid template name"
}

401 Unauthorized

object

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

429 Rate Limited

object

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 30
}

500 Server Error

object

{
  "error": "INTERNAL_SERVER_ERROR", 
  "message": "An unexpected error occurred"
}

Get Started

API Reference

Create Project

Create Project

Authentication

Request Body

Supported Formats & Limits

Supported Formats

File Limits

Response

Custom Dictionary

Webhook Integration

Error Responses

Get Started

API Reference

​Create Project

​Authentication

​Request Body

​Supported Formats & Limits

Supported Formats

File Limits

​Response

​Custom Dictionary

​Webhook Integration

​Error Responses

Create Project

Authentication

Request Body

Supported Formats & Limits

Response

Custom Dictionary

Webhook Integration

Error Responses