What video output options can I set?
fps, quality, trim, subtitle source and multi-page combine transitions, all per render.
Published ·Updated
The videoOptions object controls render-level behavior when response.format is set to "mp4", "webm", "mov", "mkv", or "gif".
Every plan renders video. The Free plan renders up to 30 seconds per video with one audio track; a longer video returns a 403 with the duration error. A plan whose video block is off returns a 403 with Video generation is available on supported plans.
For element-level video parameters (like {id}.trimStart, {id}.muted, and {id}.loop), see Video Elements.
All Options#
{
"videoOptions": {
"fps": 30,
"quality": 80,
"trimStart": 0,
"trimEnd": 20,
"duration": 8,
"muted": true,
"subtitleSource": "https://example.com/subtitles.srt",
"subtitleFontSize": "30px",
"subtitleFontWeight": "700",
"subtitleColor": "#ffffff",
"subtitleBackground": "rgba(0,0,0,0.5)",
"subtitleFontFamily": "Inter, sans-serif",
"subtitlePosition": "bottom",
"subtitleOffset": "50px",
"subtitlePaddingX": "16px",
"subtitlePaddingY": "8px",
"subtitleBorderRadius": "6px",
"subtitleWordReveal": "highlight",
"subtitleSplit": "word",
"subtitleMaxCharsPerLine": 28,
"combinePages": true,
"pageTransition": "fade",
"pageTransitionDuration": 0.5
}
}Performance and Quality#
FPS#
videoOptions.fps- Type:
number - Range:
1to30 - Controls output frame rate. When not specified, FPS is set automatically based on video length (shorter videos get higher FPS, up to 30). GIF defaults to 15 FPS.
Quality#
videoOptions.quality- Type:
number - Range:
1to100 - Higher values produce better visual quality with larger file size.
- When not set,
response.qualityis used if you send it.
Trimming and Duration#
Trim Range#
videoOptions.trimStartvideoOptions.trimEnd- Type:
number(seconds)
When both are provided, output duration is calculated as trimEnd - trimStart.
For global output trim, provide both trimStart and trimEnd together.
Duration#
videoOptions.duration- Type:
number(seconds) - Sets the video length in seconds when a trim range is not provided. It overrides the template's saved length.
Audio#
Muted#
videoOptions.muted- Type:
boolean true: force mute all output audio (video elements and page audio)false: include audio from video elements and page-level audio
Page-Level Audio#
Each page can have multiple audio tracks (e.g., background music + voiceover) configured in the Studio editor. Audio tracks are automatically mixed into the video output alongside any video element audio.
Each audio track supports:
- Volume control — adjust the mix level relative to other tracks
- Fade in / fade out — smooth audio transitions
- Trim — use a specific portion of the audio file
- Offset — delay when the audio starts playing within the page
- Loop — repeat the audio to fill the full page duration
Setting videoOptions.muted: true in the API request will mute all audio, including page-level audio tracks. When muted is not set, audio tracks are included automatically.
Audio Source#
videoOptions.audioSource- Supported forms:
string: a single audio URL applied to the first audio track on each rendered pagearray: per-page (and optionally per-track) source mapping for targeted overrides
Per-page format:
{
"videoOptions": {
"audioSource": [
{ "page": 1, "url": "https://example.com/music.mp3" },
{ "page": 1, "track": 1, "url": "https://example.com/voiceover.mp3" },
{ "pageId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "url": "https://example.com/chapter-2-music.mp3" }
]
}
}| Field | Type | Description |
|---|---|---|
page | Number | Page number to target (1-based) |
pageId | String | Page UUID to target — stable when pages are reordered. Use page or pageId, not both |
url | String | URL of the audio file |
track | Number | (Optional) Track index to override. Defaults to 0 (first track) |
When audioSource is provided as a string, it overrides the first audio track URL on each rendered page. When provided as an array, each entry targets a specific page (by page number or pageId) and track. If the target track index doesn't exist, a new track is created. Passing a single string on a multi-page render applies the same audio to every page.
The number of audio tracks per page is limited by your plan. Free and entry plans allow none. Larger plans allow 1 or 2 per page.
Subtitles#
Subtitle Source#
videoOptions.subtitleSource- Supported forms:
string: single source URL for single-page rendersarray: per-page source mapping for multi-page renders
Per-page format:
{
"videoOptions": {
"subtitleSource": [
{ "page": 1, "url": "https://example.com/intro.mp3" },
{ "page": 2, "url": "https://example.com/chapter-2.srt" }
]
}
}| Field | Type | Description |
|---|---|---|
page | Number | Page number to target (1-based) |
pageId | String | Page ID to target. Stable when pages are reordered |
url | String | Audio, video or SRT file to caption from |
offset | Number | (Optional) Seconds into the page where this audio starts. Shifts cues later |
trimStart | Number | (Optional) Seconds cut from the start of the source file. Shifts cues earlier |
Subtitle Styling#
| Option | Type | Default | Description |
|---|---|---|---|
subtitleMode | string | "phrase" | Display mode: "phrase" or "word-by-word" |
subtitleFontSize | string | "56px" | CSS font size |
subtitleFontWeight | string | "500" | Font weight ("400", "500", "600", "700", "800") |
subtitleColor | string | "#FFFFFF" | Text color |
subtitleBackground | string | "rgba(0,0,0,0.6)" | Background color of the subtitle box |
subtitleFontFamily | string | "Helvetica, Arial, sans-serif" | Font family (Google Fonts supported) |
subtitlePosition | string | "bottom" | Position: "bottom", "top", or "center" |
subtitleOffset | string | "50px" | Distance from the positioned edge (ignored for "center") |
subtitlePaddingX | string | "16px" | Horizontal padding |
subtitlePaddingY | string | "8px" | Vertical padding |
subtitleBorderRadius | string | "6px" | Corner radius of the subtitle box |
subtitleShadowX | number | 0 | Text shadow X offset (px) |
subtitleShadowY | number | 0 | Text shadow Y offset (px) |
subtitleShadowBlur | number | 0 | Text shadow blur radius (px) |
subtitleShadowColor | string | "rgba(0,0,0,0.8)" | Text shadow color |
subtitleWordSpacing | string | "14px" | Gap between words (word-by-word mode only) |
subtitleMaxWordsPerLine | number | 4 | Words per subtitle line, 2 to 8 (word-by-word mode only) |
subtitleMaxCharsPerLine | number | — | Character limit per line; overrides subtitleMaxWordsPerLine |
subtitleWordReveal | string | "appear" | "appear", "highlight", or "align" |
subtitleSplit | string | "word" | Reveal by "word" or "letter" |
subtitleActiveColor | string | — | Color of the current word |
subtitleActiveBackground | string | — | Background behind the current word |
subtitleTextTransform | string | — | Text transform such as "uppercase" |
subtitleStrokeWidth | number | 0 | Text outline width in pixels |
subtitleStrokeColor | string | "#000000" | Text outline color |
subtitleBottom still works as an alias for subtitleOffset with subtitlePosition: "bottom", but subtitleOffset + subtitlePosition is preferred.
Word-by-Word Subtitles#
Set subtitleMode: "word-by-word" to reveal each word in sync with the audio, the style used in lyric and karaoke videos on TikTok and Reels. Words of the current line appear one at a time as they are spoken or sung, and the line stays on screen until the next one starts.
{
"videoOptions": {
"subtitleSource": "https://example.com/song.mp3",
"subtitleMode": "word-by-word",
"subtitlePosition": "center",
"subtitleBackground": "transparent",
"subtitleFontFamily": "Special Elite",
"subtitleShadowBlur": 8
}
}A few tips for this mode:
- For the borderless lyric-video look, set
subtitleBackground: "transparent"and add a text shadow for readability. The default background renders a stable pill sized for the whole line. - Word timing comes from transcription. Music with heavy instrumentation can throw the transcription off. If the generated words are wrong, pass an
.srtfile with the correct lyrics assubtitleSourceinstead: word timings are then spread across each cue's duration, so your text is always right. subtitlePosition: "center"places the line in the middle of the frame and ignoressubtitleOffset.- Use
subtitleWordReveal: "highlight"for karaoke-style captions or"align"to keep the growing line centered. - Use
subtitleSplit: "letter"for a type-on effect.subtitleMaxCharsPerLinetakes priority over the word limit.
Multi-Page Combine Options#
Combine Pages#
videoOptions.combinePages- Type:
boolean - Combines multi-page video renders into one final video.
- With a
stringaudioSource, that track plays once across the whole combined video instead of restarting on each page.
Page Transition#
videoOptions.pageTransition- Type:
string - Supported values:
- Fades:
fade,fadeblack,fadewhite,dissolve - Wipes:
wipeleft,wiperight,wipeup,wipedown,wipetl,wipetr,wipebl,wipebr - Slides:
slideleft,slideright,slideup,slidedown - Smooth slides:
smoothleft,smoothright,smoothup,smoothdown - Shapes:
circleopen,circleclose,circlecrop,rectcrop,radial,distance - Splits:
horzopen,horzclose,vertopen,vertclose,diagtl,diagtr,diagbl,diagbr - Slices:
hlslice,hrslice,vuslice,vdslice - Effects:
pixelize,hblur,squeezeh,squeezev
- Fades:
- Omit or use
"none"for hard cuts.
Page Transition Duration#
videoOptions.pageTransitionDuration- Type:
number - Range:
0.1to2(seconds). Defaults to0.5. Values outside the range are clamped.
combinePages is supported only for multi-page mp4, webm, mov and
mkv renders. GIF renders always return per-page outputs.
A template with Film mode on is already one
video with its own saved transitions: an mp4 render returns the whole film,
and combinePages, pageTransition, pageTransitionDuration, duration
and audioSource are not applied. muted and fps still are.
Complete Request Example#
await fetch("https://api.orshot.com/v1/studio/render", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer <YOUR_API_KEY>",
},
body: JSON.stringify({
templateId: "<YOUR_TEMPLATE_ID>",
modifications: {
"page1@title": "Intro",
"page2@title": "Features",
"page3@title": "CTA",
},
response: {
format: "webm",
type: "url",
includePages: [1, 2, 3],
},
videoOptions: {
fps: 30,
quality: 80,
muted: true,
combinePages: true,
pageTransition: "fade",
pageTransitionDuration: 0.5,
subtitleSource: [
{ page: 1, url: "https://example.com/intro.mp3" },
{ page: 2, url: "https://example.com/chapter2.mp3" },
],
subtitleFontSize: "30px",
subtitleColor: "#ffffff",
subtitleBackground: "rgba(0,0,0,0.5)",
},
}),
});Ready to automate?
Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.
Get your API key- Image, PDF and video generation via API
- Visual editor with AI and smart layouts
- Zapier, Make, MCP and 40+ integrations
- White-label embed for your own app
- 100 free credits a month, no credit card required