Generate Video

Create a new video generation job.

Endpoint

POST /api/v1/video/generate

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes	Must be `application/json`

Request Body

{
  "videoType": "narrated",
  "topic": "5 Tips for Better Sleep",
  "script": "Here are five science-backed tips for better sleep that will transform your nights...",
  "voiceId": "joanna",
  "brollKeys": [
    "users/abc123/b-roll/sleep-bedroom.mp4",
    "users/abc123/b-roll/morning-routine.mp4"
  ],
  "musicKey": "shared/music/calm-ambient.mp3",
  "assetTrimSettings": {
    "users/abc123/b-roll/sleep-bedroom.mp4": {
      "startTime": 2.5,
      "endTime": 10.0
    }
  },
  "aspectRatio": "9:16",
  "scriptDuration": 30,
  "captionSize": "medium",
  "tone": "professional"
}

Parameters

Required Parameters

Parameter	Type	Description
`videoType`	string	Type of video: `"narrated"` or `"cinematic"`
`topic`	string	Video topic/title (max 500 characters)
`brollKeys`	string[]	Array of B-roll asset S3 keys (1-20 items)

Conditional Parameters

Parameter	Type	Required When	Description
`script`	string	`videoType: "narrated"`	Narration script (max 5000 characters)
`voiceId`	string	`videoType: "narrated"` (if no `voiceoverKey`)	AWS Polly voice ID
`voiceoverKey`	string	Alternative to `voiceId`	S3 key of pre-generated voiceover

Optional Parameters

Parameter	Type	Default	Description
`musicKey`	string	`null`	S3 key of background music
`voiceoverSpeechMarksKey`	string	`null`	S3 key of speech marks file (for word-level captions)
`assetTrimSettings`	object	`{}`	Trim settings per asset
`aspectRatio`	string	`"9:16"`	Video aspect ratio
`scriptDuration`	number	`30`	Target duration in seconds
`captionSize`	string	`"medium"`	Caption size
`tone`	string	`"professional"`	Content tone
`brandPreset`	object	`null`	Brand preset configuration

Parameter Details

videoType

Value	Description
`"narrated"`	Video with AI voiceover and synchronized captions
`"cinematic"`	Music-only video without narration

voiceId

Available AWS Polly voices:

Voice ID	Language	Gender	Description
`joanna`	English (US)	Female	Clear, professional
`matthew`	English (US)	Male	Warm, conversational
`amy`	English (UK)	Female	British accent
`brian`	English (UK)	Male	British accent
`emma`	English (UK)	Female	British accent
`ivy`	English (US)	Female	Child voice
`kendra`	English (US)	Female	Professional
`kimberly`	English (US)	Female	Conversational
`salli`	English (US)	Female	Soft, friendly
`joey`	English (US)	Male	Casual
`justin`	English (US)	Male	Child voice
`kevin`	English (US)	Male	Child voice

For other languages, see the Voices and Languages documentation.

aspectRatio

Value	Description	Best For
`"9:16"`	Portrait (1080x1920)	TikTok, Reels, Shorts
`"16:9"`	Landscape (1920x1080)	YouTube, Twitter
`"1:1"`	Square (1080x1080)	Instagram Feed

scriptDuration

Value	Description	Approximate Word Count
`15`	15 seconds	~40 words
`30`	30 seconds	~80 words
`45`	45 seconds	~120 words
`60`	60 seconds	~160 words

captionSize

Value	Description
`"small"`	Subtle, minimal captions
`"medium"`	Balanced, readable
`"large"`	Bold, attention-grabbing

tone

Value	Description
`"professional"`	Clear, formal, objective
`"casual"`	Relaxed, conversational, friendly
`"humorous"`	Funny, witty, entertaining
`"inspirational"`	Uplifting, encouraging, motivational
`"educational"`	Informative, instructive, clear

assetTrimSettings

Specify start and end times (in seconds) for each B-roll clip:

{
  "assetTrimSettings": {
    "users/abc123/b-roll/clip1.mp4": {
      "startTime": 0,
      "endTime": 5.5
    },
    "users/abc123/b-roll/clip2.mp4": {
      "startTime": 3.0,
      "endTime": 8.0
    }
  }
}

Field	Type	Description
`startTime`	number	Start time in seconds (must be ≥ 0)
`endTime`	number	End time in seconds (must be > startTime)

brollKeys

Array of S3 keys pointing to video assets in your library:

{
  "brollKeys": [
    "users/abc123/b-roll/intro.mp4",
    "users/abc123/b-roll/main-content.mp4",
    "shared/b-roll/outro.mp4"
  ]
}

Constraints:

Minimum: 1 item
Maximum: 20 items
Must be valid paths in your asset library or shared library

Valid path prefixes:

users/{your-user-id}/b-roll/
shared/b-roll/

brandPreset

Apply brand styling to captions:

{
  "brandPreset": {
    "id": "preset-123",
    "name": "My Brand",
    "primaryColor": "#00D4FF",
    "secondaryColor": "#0066FF",
    "fontFamily": "Inter"
  }
}

Response

Success Response (200)

{
  "success": true,
  "message": "Video generation job queued successfully",
  "projectId": "abc123def456",
  "correlationId": "vid_lxyz789_a1b2c3d4"
}

Field	Type	Description
`success`	boolean	Always `true` for success
`message`	string	Human-readable status message
`projectId`	string	Unique ID to track this video generation
`correlationId`	string	Request tracing ID for debugging

Error Responses

400 Bad Request

{
  "success": false,
  "message": "script is required for narrated videos",
  "code": "VALIDATION_ERROR"
}

401 Unauthorized

{
  "success": false,
  "message": "Unauthorized. Please provide a valid API key via the X-API-Key header.",
  "code": "UNAUTHORIZED"
}

402 Payment Required

{
  "success": false,
  "message": "Video generation quota exhausted. Please upgrade your plan or wait for quota reset.",
  "code": "QUOTA_EXCEEDED"
}

429 Too Many Requests

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMITED",
  "details": {
    "resetAt": "2025-01-21T17:00:00.000Z"
  }
}

Examples

Narrated Video (Minimal)

curl -X POST https://reelbot.space/api/v1/video/generate \
  -H "X-API-Key: rb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoType": "narrated",
    "topic": "Morning Routine Tips",
    "script": "Start your day right with these simple morning routine tips that will boost your productivity.",
    "voiceId": "joanna",
    "brollKeys": ["users/abc123/b-roll/morning.mp4"]
  }'

Narrated Video (Full Options)

curl -X POST https://reelbot.space/api/v1/video/generate \
  -H "X-API-Key: rb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoType": "narrated",
    "topic": "5 Productivity Hacks",
    "script": "Here are five productivity hacks that will transform your workday. First, time blocking. Schedule specific tasks for specific times. Second, the two-minute rule. If it takes less than two minutes, do it now.",
    "voiceId": "matthew",
    "brollKeys": [
      "users/abc123/b-roll/desk-setup.mp4",
      "users/abc123/b-roll/calendar.mp4",
      "users/abc123/b-roll/typing.mp4"
    ],
    "musicKey": "shared/music/upbeat-corporate.mp3",
    "assetTrimSettings": {
      "users/abc123/b-roll/desk-setup.mp4": {
        "startTime": 0,
        "endTime": 8
      }
    },
    "aspectRatio": "9:16",
    "scriptDuration": 30,
    "captionSize": "large",
    "tone": "professional"
  }'

Cinematic Video (No Narration)

curl -X POST https://reelbot.space/api/v1/video/generate \
  -H "X-API-Key: rb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "videoType": "cinematic",
    "topic": "City Vibes",
    "brollKeys": [
      "users/abc123/b-roll/city-night.mp4",
      "users/abc123/b-roll/traffic.mp4",
      "users/abc123/b-roll/skyline.mp4"
    ],
    "musicKey": "shared/music/chill-lofi.mp3",
    "aspectRatio": "9:16",
    "scriptDuration": 15
  }'

Next Steps

→ Check Status — Poll for video generation progress

→ Download Video — Get the completed video file

Endpoint​

Headers​

Request Body​

Parameters​

Required Parameters​

Conditional Parameters​

Optional Parameters​

Parameter Details​

videoType​

voiceId​

aspectRatio​

scriptDuration​

captionSize​

tone​

assetTrimSettings​

brollKeys​

brandPreset​

Response​

Success Response (200)​

Error Responses​

400 Bad Request​

401 Unauthorized​

402 Payment Required​

429 Too Many Requests​

Examples​

Narrated Video (Minimal)​

Narrated Video (Full Options)​

Cinematic Video (No Narration)​

Next Steps​