Skip to main content
POST
https://api.submagic.co
/
v1
/
projects
/
upload
curl -X POST "https://api.submagic.co/v1/projects/upload" \
  -H "x-api-key: sk-your-api-key-here" \
  -F "title=My Uploaded Video" \
  -F "language=en" \
  -F "file=@./video.mp4" \
  -F "templateName=Hormozi 2" \
  -F 'items=[{"type":"user-media","startTime":5,"endTime":10,"userMediaId":"123e4567-e89b-12d3-a456-426614174000"},{"type":"ai-broll","startTime":15,"endTime":21,"prompt":"drone shot of a modern city skyline at dusk"}]' \
  -F "webhookUrl=https://yoursite.com/webhook/submagic" \
  -F 'dictionary=["Submagic", "AI-powered", "captions"]' \
  -F "magicZooms=true" \
  -F "magicBrolls=true" \
  -F "magicBrollsPercentage=75" \
  -F "removeSilencePace=fast" \
  -F "removeBadTakes=true" \
  -F 'hookTitle={"text":"Stop scrolling—watch this in 30 seconds","template":"tiktok","top":45,"size":32}'

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

​
Upload Project

Create a new video project by uploading a video file directly to Submagic. This endpoint accepts multipart/form-data uploads and is ideal for applications where you have video files stored locally or want to upload directly from user devices.
This endpoint requires authentication and has a rate limit of 500 requests per hour due to the resource-intensive nature of file uploads.

​
Authentication

​
x-api-key
string
required
Your Submagic API key starting with sk-

​
Request Body (multipart/form-data)

​
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.
​
file
file
required
Video file to upload. Must be in a supported format and under 2GB.
​
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 its name.
​
hookTitle
string
Adds an animated hook caption. Pass "true" to enable the default hook, or pass a JSON string such as {"text":"Stop scrolling—watch this in 30 seconds","template":"tiktok","top":45,"size":32}.
  • text: Optional custom copy (1-100 characters)
  • template: Optional template name (defaults to "tiktok"). Use the hook title templates endpoint to discover valid names.
  • top: Optional vertical position between 0-80 (default 50)
  • size: Optional font size between 0-80 (default 30)
Template names are validated before the upload begins; invalid names return a VALIDATION_ERROR.
​
webhookUrl
string
URL to receive webhook notifications when processing is complete. Must be a valid HTTPS URL.
​
dictionary
string
JSON array string of custom words or phrases to improve transcription accuracy (max 100 items, 50 characters each).
​
items
string
JSON string describing optional items to insert into the video. Pass an array of objects. 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 entries cannot overlap in time. When present, this metadata is parsed after the upload completes and queued for rendering.
​
magicZooms
string
Enable automatic zoom effects on the video to enhance visual engagement. Pass “true” or “false” as string. Optional, defaults to “false”.
​
magicBrolls
string
Enable automatic B-roll insertion to enhance video content with relevant supplementary footage. Pass “true” or “false” as string. Optional, defaults to “false”.
​
magicBrollsPercentage
string
Percentage of automatic B-rolls to include in the video (0-100). Pass as string. Only effective when magicBrolls is enabled. Optional, defaults to “50”.
​
removeSilencePace
string
Automatically remove silence from the video at the specified pace. Pass as string. 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
string
Automatically detect and remove bad takes and silence from the video using AI analysis. Pass “true” or “false” as string. Optional, defaults to “false”.

​
Supported Formats & Limits

Supported Formats

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

File Limits

  • Max size: 2GB - Max duration: 2 hours
curl -X POST "https://api.submagic.co/v1/projects/upload" \
  -H "x-api-key: sk-your-api-key-here" \
  -F "title=My Uploaded Video" \
  -F "language=en" \
  -F "file=@./video.mp4" \
  -F "templateName=Hormozi 2" \
  -F 'items=[{"type":"user-media","startTime":5,"endTime":10,"userMediaId":"123e4567-e89b-12d3-a456-426614174000"},{"type":"ai-broll","startTime":15,"endTime":21,"prompt":"drone shot of a modern city skyline at dusk"}]' \
  -F "webhookUrl=https://yoursite.com/webhook/submagic" \
  -F 'dictionary=["Submagic", "AI-powered", "captions"]' \
  -F "magicZooms=true" \
  -F "magicBrolls=true" \
  -F "magicBrollsPercentage=75" \
  -F "removeSilencePace=fast" \
  -F "removeBadTakes=true" \
  -F 'hookTitle={"text":"Stop scrolling—watch this in 30 seconds","template":"tiktok","top":45,"size":32}'

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

​
Error Responses

​
400 Validation Error
object
{
  "error": "VALIDATION_ERROR",
  "message": "File validation failed",
  "details": [
    {
      "field": "file",
      "message": "File size exceeds 10GB limit",
      "value": null
    }
  ]
}
​
413 Payload Too Large
object
{
  "error": "PAYLOAD_TOO_LARGE",
  "message": "File size exceeds maximum allowed size"
}
​
415 Unsupported Media Type
object
{
  "error": "UNSUPPORTED_MEDIA_TYPE",
  "message": "Video format not supported"
}
​
400 Invalid Hook Title Template
object
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid template name"
}