API Reference
Create Project
Create a new video project using a video URL for AI-powered caption generation
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 characterstemplate(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 to50.size(optional): Font size (0-80). Defaults to30.
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 removalboolean
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 failedstring
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 ellaboolean
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-fastboolean
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:- 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:Error Responses
object
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

