Working with Video
Video layers are the foundation of most Reel Forge compositions. They allow you to place video assets onto the timeline, optionally trimming them, and controlling how they scale within your composition.
Basic Video Object
A basic video layer requires an id, type, asset_id, and time positioning. When is time required? For video (and audio) layers, time is required unless composition.auto_stitch is true—in that case, timing is derived automatically from clip order.
{
"id": "main-video",
"type": "video",
"asset_id": "asset-video-1",
"time": {
"start_seconds": 0,
"duration_seconds": 5
}
}
Auto-Stitching & Arrays
If you don't want to calculate exact timeline mathematics (start_seconds), Reel Forge supports auto_stitch. When enabled on the root composition object, you can omit the time property from video layers. Reel Forge will probe durations and play clips in timeline order.
This also works for a single base video clip (for example: talking-head + logo overlay) when you do not want to precompute duration.
{
"composition": {
"auto_stitch": true,
"timeline": [
{
"id": "clip-1",
"type": "video",
"asset_id": "asset-video-1"
},
{
"id": "clip-2",
"type": "video",
"asset_id": "asset-video-2"
}
]
}
}
Single Talking-Head + Logo (No Manual Duration)
You can omit the base video duration and let ReelForge infer it with auto_stitch.
{
"composition": {
"auto_stitch": true,
"timeline": [
{
"id": "base-video",
"type": "video",
"asset_id": "asset-video-1"
},
{
"id": "logo-overlay",
"type": "image",
"asset_id": "asset-logo-1",
"time": { "start_seconds": 0 },
"background_mode": "transparent",
"layout": {
"x": "82%",
"y": "88%",
"width": "12%",
"height": "8%",
"fit": "contain",
"z_index": 20
}
}
]
}
}
Z-Index Stacking
By default, layers are drawn back-to-front based on their order in the timeline array. The first layer is the bottom-most background, and the last layer is on top.
You can explicitly override this by providing a z_index inside the layout object.
{
"id": "foreground-video",
"type": "video",
"asset_id": "asset-video-1",
"layout": {
"z_index": 100
}
}
Background Mode & Letterboxing
When you place a video with a different aspect ratio than your composition (e.g., a 16:9 landscape video into a 9:16 portrait composition), Reel Forge must pad the empty space.
You can control this using the background_mode property:
"blurred"(Default): Creates a cinematic blurred and zoomed version of your video to fill the background."solid": Fills the empty space with a solid black background."transparent": Leaves the empty space transparent, allowing layers beneath it (lower z-index) to show through.
{
"id": "landscape-clip",
"type": "video",
"asset_id": "asset-landscape-video",
"background_mode": "blurred",
"layout": {
"fit": "contain"
}
}
The Full Video Request Example
Here is a complete payload placing two videos sequentially using explicit timings, with the first video using a solid background mode.
curl -X POST https://api.reelforger.com/v1/videos/render \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"version": "v1",
"output": {
"width": 1080,
"height": 1920,
"fps": 30
},
"assets": [
{
"id": "asset-1",
"type": "video",
"url": "https://example.com/video1.mp4"
},
{
"id": "asset-2",
"type": "video",
"url": "https://example.com/video2.mp4"
}
],
"composition": {
"timeline": [
{
"id": "layer-1",
"type": "video",
"asset_id": "asset-1",
"background_mode": "solid",
"time": {
"start_seconds": 0,
"duration_seconds": 5
}
},
{
"id": "layer-2",
"type": "video",
"asset_id": "asset-2",
"time": {
"start_seconds": 5,
"duration_seconds": 5
}
}
]
}
}'