Video Generation API

Endpoint

POST /video/exports accepts multipart/form-data. Send Accept: application/json to receive export metadata with a download_url.

Form Fields

tier_list

Required JSON string with title, rows, and items.

timeline_data

Required JSON string with videos, audios, tier_blocks, tier_tiles, subtitles, and soundtracks. tier_block is accepted as an alias for tier_blocks.

settings

Optional JSON string for export dimensions, frame rate, quality, encoder preset, audio bitrate, and file name.

Media files

Upload each file under the exact file_field names referenced by tier_list.items[] and timeline entries.

Schema

{
  "tier_list": {
    "title": "Launch tiers",
    "rows": [
      { "id": "s", "label": "S", "color": "#fc7c78", "item_ids": ["tile-one"] }
    ],
    "items": [
      { "id": "tile-one", "name": "Tile One", "file_field": "tile_one_image" }
    ]
  },
  "timeline_data": {
    "videos": [
      {
        "id": "clip-one",
        "file_field": "clip_one_video",
        "start": 0,
        "duration": 4,
        "trim_start": 0,
        "trim_end": 4,
        "crop_x": 0,
        "crop_y": 0,
        "crop_w": 100,
        "crop_h": 100,
        "speed": 1,
        "volume": 1
      }
    ],
    "audios": [],
    "soundtracks": [],
    "tier_blocks": [
      { "id": "tier-window", "start": 1, "duration": 3, "x_percent": 50, "y_percent": 50, "width_percent": 80, "height_percent": 45 }
    ],
    "tier_tiles": [
      { "id": "tile-reveal", "tier_item_id": "tile-one", "position": 1.25 }
    ],
    "subtitles": [
      { "id": "caption", "text": "Final pick", "start": 2, "duration": 1.5, "size": 32, "align": "center", "text_color": "#ffffff", "background_color": "#191c1e", "background_alpha": 80 }
    ]
  },
  "settings": {
    "preset": "tiktok",
    "fps": 30,
    "quality": "balanced"
  }
}

Timeline Arrays

• videos[]: video clips rendered visually. Supports id, file_field, start, duration, trim fields, crop fields, speed, and volume.
• audios[]: video-backed audio lane clips. Uses the same source and timing fields as videos[], but renders audio only.
• soundtracks[]: audio-file lane clips. Supports id, file_field, start, duration, trim fields, and volume.
• tier_blocks[]: tier-list overlay windows with start, duration, and position/size percents.
• tier_tiles[]: reveal events for tier items with tier_item_id and position.
• subtitles[]: text overlays with text, timing, size, alignment, colors, alpha, and position/size percents.

Multipart Example

curl -X POST http://127.0.0.1:3055/video/exports \
  -H "Accept: application/json" \
  -F 'tier_list={"title":"Launch tiers","rows":[{"id":"s","label":"S","color":"#fc7c78","item_ids":["tile-one"]}],"items":[{"id":"tile-one","name":"Tile One","file_field":"tile_one_image"}]}' \
  -F 'timeline_data={"videos":[{"id":"clip-one","file_field":"clip_one_video","start":0,"duration":4,"trim_start":0,"trim_end":4}],"audios":[],"tier_blocks":[{"id":"tier-window","start":1,"duration":3}],"tier_tiles":[{"id":"tile-reveal","tier_item_id":"tile-one","position":1.25}],"subtitles":[],"soundtracks":[]}' \
  -F 'settings={"preset":"tiktok","fps":30,"quality":"balanced"}' \
  -F 'clip_one_video=@clip.mp4;type=video/mp4' \
  -F 'tile_one_image=@tile-one.png;type=image/png'

Response

{
  "ok": true,
  "export_id": "4cf2b9b2-1737-4bf1-8f43-d2f88c5a4f98",
  "download_url": "/video/exports/4cf2b9b2-1737-4bf1-8f43-d2f88c5a4f98/download/tiktok",
  "downloads": {
    "tiktok": "/video/exports/4cf2b9b2-1737-4bf1-8f43-d2f88c5a4f98/download/tiktok",
    "shorts": "/video/exports/4cf2b9b2-1737-4bf1-8f43-d2f88c5a4f98/download/shorts",
    "reels": "/video/exports/4cf2b9b2-1737-4bf1-8f43-d2f88c5a4f98/download/reels"
  },
  "settings": {
    "preset": "tiktok",
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "quality": "balanced"
  }
}

Legacy Fields

Existing clients can keep using timeline_json with media_manifest. The public tier_list and timeline_data fields are additive.