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",
    "webhookUrl": "https://yoursite.com/webhook/submagic",
    "dictionary": ["Submagic", "AI-powered", "captions"],
    "magicZooms": true,
    "magicBrolls": true,
    "magicBrollsPercentage": 75
  }'

{
  "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,
  "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 30 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.
​
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.
​
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).
​
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.

​
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
​
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)
​
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",
    "webhookUrl": "https://yoursite.com/webhook/submagic",
    "dictionary": ["Submagic", "AI-powered", "captions"],
    "magicZooms": true,
    "magicBrolls": true,
    "magicBrollsPercentage": 75
  }'

{
  "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,
  "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://cdn.submagic.co/output/your-video.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"
    }
  ]
}
​
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"
}