Skip to main content
POST
/
v1
/
projects
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"
}

​
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.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.
​
autoRender
boolean
Whether to automatically render the final video once transcription completes. Optional, defaults to true.Set to false to keep the project editable: after transcription the project stays in completed status without a rendered video, and the completed webhook fires so you know it’s ready. You can then fetch the transcript with Get Project, edit the captions with Update Project (the words field), and trigger the render yourself with Export Project.
​
music
object
Optional background music track that spans the full project duration.

​
Supported Formats & Limits

Supported Formats

  • MP4 (.mp4) - MOV (.mov)

File Limits

  • Max size: 2GB - Max duration: 2 hours

​
Response

​
id
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"
}
​
400 Unsupported Social Media URL
object
{
  "error": "VALIDATION_ERROR",
  "message": "URLs from social media platforms are not supported. Please use a direct download link."
}
​
400 Google Drive Folder Link
object
Returned when videoUrl is a Google Drive folder or other Drive link that doesn’t point to a single file. Share a direct file link with access set to “Anyone with the link”.
{
  "error": "VALIDATION_ERROR",
  "message": "This looks like a Google Drive folder or an unsupported Drive link. Please share a direct link to a single file (e.g. https://drive.google.com/file/d/FILE_ID/view) with access set to \"Anyone with the link\"."
}
​
400 URL Not Downloadable
object
Returned when videoUrl can’t be reached or serves a web page instead of a media file (e.g. a broken link, a login wall, or a share page rather than a direct download).
{
  "error": "VALIDATION_ERROR",
  "message": "The provided URL does not point to a downloadable media file. Please provide a direct download link to a video, audio, or image file."
}
​
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"
}