Step 1 — Estimate Durations
Send your narration script texts along with a voice ID. VoiceLayer resolves the voice against stored voice profiles or default library voices to return calibrated Words Per Second (WPS) rates and estimated durations per narration block.
Request (POST /api/estimate-durations)
POST https://voicelayer.studio/api/estimate-durations
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
"voice_id": "NNl6r8mD7vthiJatiJt1",
"narrations": [
{ "text": "Welcome to our channel today." },
{ "text": "Subscribe and hit the bell icon." }
]
}
Response (HTTP 200 OK)
{
"voice_id": "NNl6r8mD7vthiJatiJt1",
"wps": 2.8,
"wps_source": "api_calibrated",
"estimates": [
{ "index": 0, "word_count": 5, "raw_duration_s": 1.79, "safe_duration_s": 6.79 },
{ "index": 1, "word_count": 6, "raw_duration_s": 2.14, "safe_duration_s": 7.14 }
]
}
Step 2 — Submit Compile Job
Calculate start timestamps using Step 1 estimates, then submit your compile request. The VoiceLayer backend will upload your source video to S3 storage first, confirm the upload, dispatch the compilation request to n8n, and immediately return status: "processing".
Request (POST /api/compile)
POST https://voicelayer.studio/api/compile
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"video_url": "https://cdn.example.com/public/sample_video.mp4",
"mute_where_speech": "true",
"narrations": [
{
"timestamp": "00:05.093",
"text": "[impressed] Wow this van looks so futuristic.",
"font": "Comic Sans MS",
"effect": "karaoke",
"text_color": "#33FF5C",
"effect_color": "#FF00DD",
"aspect_ratio": "9:16",
"voice_id": "NNl6r8mD7vthiJatiJt1",
"subtitles": true,
"x_position": 540,
"y_position": 1660,
"size": 1
},
{
"timestamp": "00:10.187",
"text": "You think I can get myself one here in the US?",
"font": "Comic Sans MS",
"effect": "word_stack",
"text_color": "#33FF5C",
"effect_color": "#FF00DD",
"aspect_ratio": "9:16",
"voice_id": "NNl6r8mD7vthiJatiJt1",
"subtitles": true,
"x_position": 540,
"y_position": 1660,
"size": 1.2
}
]
}
Response (HTTP 200 OK — Asynchronous Acceptance)
{
"job_id": "64249205186211521157",
"status": "processing"
}
Step 3 — Check Job Status
Poll the status endpoint periodically (e.g. every 5 seconds) using the returned job_id until processing completes.
Request (GET /api/jobs/:job_id)
GET https://voicelayer.studio/api/jobs/64249205186211521157
X-API-Key: YOUR_API_KEY
Response — In Progress
{
"job_id": "64249205186211521157",
"status": "processing"
}
Response — Completed (HTTP 200 OK)
{
"job_id": "64249205186211521157",
"status": "done",
"video_url": "https://voicelayer.studio/media/64249205186211521157.mp4"
}
Response — Failed
{
"job_id": "64249205186211521157",
"status": "error",
"error_detail": "Video rendering failed: narration alignment timeout"
}
Complete API Field Reference
Authentication: All REST API calls require an X-API-Key header containing your VoiceLayer API key.
Video URL Requirements: video_url must point directly to a publicly accessible media file (e.g. .mp4, .mov, .webm, or CDN link). Standard webpage URLs (such as YouTube watch pages) are not direct video files.
Watermark Policy: The watermark field is strictly managed server-side based on your VoiceLayer subscription ("false" for active subscribers/devs, "true" for free accounts). Clients cannot supply or override this parameter.
Narration Block Schema
timestamp (string, required) — Start offset format MM:SS.ms (e.g. 00:05.093).text (string, required) — Script for narration TTS synthesis. Supports emotion tags (e.g. [impressed]).voice_id (string, required) — Voice identifier resolved against default library voices or saved user voice profiles.subtitles (boolean) — Set to true to generate animated captions. Default true.font (string) — Font family for subtitle text.effect (string) — Animation style effect for subtitle words.text_color (string) — Hex color string for main caption text (e.g. #FFFFFF).effect_color (string) — Hex color string for effect highlight/box accent (e.g. #FF00DD).aspect_ratio (string) — Video aspect ratio context (9:16, 1:1, 16:9).x_position (number) — Horizontal center pixel position on the video canvas.y_position (number) — Vertical pixel position on the video canvas (measured from top).size (number) — Subtitle scale factor (default 1).
Supported Fonts
Arial, Comic Sans MS, Trebuchet MS, Impact, Courier New, Georgia, Times New Roman, Verdana. Unsupported fonts fallback to Arial.
Supported Subtitle Effects
karaoke — Flashes a highlighted accent box behind each active spoken word.word_stack — Highlights current word in effect color and dims spoken words to gray.word_pop — Bounces/scales current spoken word up to 120% size.uppercase — Dynamically converts currently active word to UPPERCASE.lowercase — Renders entire subtitle block in lowercase.fade — Smoothly fades phrase in and out.phrase_slide — Slides phrase upward into frame from below.
Aspect Ratios & Canvas Coordinate Systems
9:16 (Vertical Mobile Shorts/Reels) — Canvas size: 1080 × 1920 px. Recommended position: x: 540, y: 1660.1:1 (Square Posts) — Canvas size: 1080 × 1080 px. Recommended position: x: 540, y: 900.16:9 (Horizontal Widescreen) — Canvas size: 1920 × 1080 px. Recommended position: x: 960, y: 960.
HTTP Response Status Codes
200 OK — Request processed or job accepted for processing.400 Bad Request — Missing header/body or malformed JSON payload.401 Unauthorized — Missing or invalid X-API-Key.404 Not Found — Voice ID or Job ID not found.422 Unprocessable Entity — Invalid narration parameters.502 Bad Gateway — Upstream S3 upload or n8n compilation service failure.500 Internal Server Error — Server environment configuration error.