Skip to main content
POST

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

string
required
Your Submagic API key starting with sk-

Request Body

string
required
A descriptive title for your video project (1-100 characters)
string
required
Language code for transcription (e.g., “en”, “es”, “fr”). Use the languages endpoint to get available options.
string
required
Public URL to your video file. Must be accessible without authentication and in a supported format.
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.
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, removeBadTakes, captionPositionY, or captionPositionX — the preset already controls these settings.
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.
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.
number
Vertical caption position as a percentage from the top of the frame (0-80). Overrides the position of the selected template or theme. Cannot be combined with presetId or aiEditTemplate.
number
Horizontal caption position as a percentage (0-100, 50 = centered). Overrides the position of the selected template or theme. Cannot be combined with presetId or aiEditTemplate.
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.
string
URL to receive webhook notifications when processing is complete. Must be a valid HTTPS URL.
array
Array of custom words or phrases to improve transcription accuracy (max 100 items, 50 characters each).
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.
boolean
Enable automatic zoom effects on the video to enhance visual engagement. Optional, defaults to false.
boolean
Enable automatic B-roll insertion to enhance video content with relevant supplementary footage. Optional, defaults to false.
number
Percentage of automatic B-rolls to include in the video (0-100). Only effective when magicBrolls is enabled. Optional, defaults to 50.
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
boolean
Automatically detect and remove bad takes and silence from the video using AI analysis. Optional, defaults to false.
boolean
Enable AI-powered audio cleanup that removes background noises from the video. Optional, defaults to false.
boolean
Hide captions from the exported video. Optional, defaults to false.
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.
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

string
Unique identifier for the created project (UUID format)
string
The title you provided for the project
string
Language code used for transcription
string
Current processing status: processing, transcribing, exporting, completed, or failed
string
Webhook URL if provided in the request
string
Template name applied to the project
string
User theme ID applied to the project
string
Preset ID applied to the project
string
AI edit template applied to the project (if any): kelly, karl, or ella
boolean
Whether automatic zoom effects are enabled for the video
boolean
Whether automatic B-roll insertion is enabled for the video
number
Percentage of automatic B-rolls to include in the video (0-100)
string
Pace setting for automatic silence removal: natural, fast, or extra-fast
boolean
Whether automatic bad takes and silence removal is enabled
boolean
Whether AI-powered audio cleanup is enabled
number
Vertical caption position override (0-80), echoed back when provided
number
Horizontal caption position override (0-100), echoed back when provided
string
ISO 8601 timestamp when the project was created
string
ISO 8601 timestamp when the project was last updated

Custom Dictionary

Improve transcription accuracy by providing custom terms:
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:
Your webhook endpoint will receive a POST request:

Error Responses

object
object
object
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”.
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).
object
object
object