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

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

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

{
  "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,
  "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"
}