Skip to navigation

Generation Templates

One-field effects and Compose recipes for AI video. Apply curated effects to normal generations, or plan and render a full short-form production.

Generation Templates includes two related surfaces:

  • Effect templates: pre-curated creative effects for /v1/images/generations and /v1/videos/generations. Pass template: "<slug>" and EmpirioLabs applies the tuned effect to a normal generation request.
  • Compose recipes: full-production short-form video workflows. Compose plans scenes, creates or selects visuals, generates voiceover, captions, optional music, and returns a finished MP4.

The same catalog powers the Templates button in the dashboard Playground, where Effects and Compose appear as top-level tabs. Everything on this page can also be run visually there, with live previews for each effect and recipe; open the Compose tab directly for the full-production recipes.

List templates

GET
/v1/templates
curl https://api.empiriolabs.ai/v1/templates

Use the generic endpoint for the full image and video catalog, or the modality-specific endpoints when you already know the generation type.

curl https://api.empiriolabs.ai/v1/templates?modality=image \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

List video templates

GET
/v1/videos/templates
curl https://api.empiriolabs.ai/v1/videos/templates

Filters

  • category: viral, cinematic, motion, transform, social, extend, product, edit, portrait
  • modality: video or image
  • model: only return templates that support a specific model slug
  • featured: true to filter to featured templates only
curl https://api.empiriolabs.ai/v1/videos/templates?category=viral \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Response shape

{
"object": "list",
"template_count": 11,
"data": [
{
"slug": "baseball-stadium",
"display_name": "Stadium",
"category": "viral",
"description": "Customer-facing description shown in the playground card.",
"recommended_model": "kling-o3",
"supported_models": ["kling-o3"],
"default_params": { "aspect_ratio": "16:9", "duration": 10 },
"required_inputs": { "image": true, "min_images": 1, "max_images": 1 },
"cover_image_url": "https://media.empiriolabs.ai/assets/template-posters/baseball-stadium.jpg",
"preview_video_url": "https://media.empiriolabs.ai/assets/template-previews/baseball-stadium.mp4",
"modality": "video",
"is_featured": true,
"display_order": 10
}
]
}

List image templates

GET
/v1/images/templates
curl https://api.empiriolabs.ai/v1/images/templates
curl https://api.empiriolabs.ai/v1/images/templates?model=seedream-5-0-lite \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Compose

Compose is the full-production video workflow. Use it when you want a complete short-form video from a brief, script, product idea, or explainable topic. Use effect templates when you want one curated effect applied to a normal image or video generation request.

List Compose recipes

GET
/v1/videos/compose/recipes
curl https://api.empiriolabs.ai/v1/videos/compose/recipes
curl https://api.empiriolabs.ai/v1/videos/compose/recipes

The response includes public recipe metadata:

  • slug: pass this as recipe on POST /v1/videos/compose
  • display_name, category, visual_mode, and audio_mode
  • scene_count (default, min, and max), aspect_ratios, and default_caption_style
  • requires_face_image and accepts_product_image
  • models: recommended and allowed model options by stage

Model recommendations are read from the live Compose recipe catalog. If you override a stage model, use a value listed in that recipe’s models.<stage>.options.

Plan a storyboard

Use mode: "plan" to turn a topic or script into an editable storyboard. This is the fastest way to preview structure before spending on a full render.

POST
/v1/videos/compose
curl -X POST https://api.empiriolabs.ai/v1/videos/compose \
-H "Authorization: Bearer <token>"
curl https://api.empiriolabs.ai/v1/videos/compose \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipe": "custom",
"mode": "plan",
"brief": "Explain why cold plunge clips went viral.",
"aspect_ratio": "9:16",
"scene_count": 5,
"caption_style": "bold-white"
}'

Compose returns an async job:

{
"job_id": "5f3c9a2e-8d14-4b6f-a0e7-1c2d3e4f5a6b",
"status": "processing",
"poll_url": "/v1/jobs/5f3c9a2e-8d14-4b6f-a0e7-1c2d3e4f5a6b"
}

Poll the job:

curl https://api.empiriolabs.ai/v1/jobs/5f3c9a2e-8d14-4b6f-a0e7-1c2d3e4f5a6b \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

When the plan job completes, result contains a storyboard. You can edit that JSON before render.

Render the video

Send the storyboard back with mode: "render".

curl https://api.empiriolabs.ai/v1/videos/compose \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipe": "custom",
"mode": "render",
"storyboard": {
"title": "Why cold plunge clips took over",
"aspect_ratio": "9:16",
"caption_style": "bold-white",
"scenes": [
{
"index": 1,
"narration": "Cold plunges look extreme, but the hook is simple.",
"visual_prompt": "Fast vertical b-roll of ice, water, and a phone recording setup.",
"duration_seconds": 4
}
]
}
}'

The final job result includes the output URL and Compose metadata. Generated media URLs expire after 7 days, so save anything you need to keep.

Edit a render

Use mode: "edit" to change selected scenes of a finished render. Send the manifest from the render job’s result unchanged, plus edits. Each edit names a scene by its zero-based position in manifest.scenes (scene_index) and an action:

  • regen_visual makes the scene’s visual again.
  • edit_caption sets the scene’s caption to value; without value the caption is cleared.
  • redo_vo sets the scene’s narration to value and redoes the voiceover.
{
"recipe": "custom",
"mode": "edit",
"manifest": { "version": 1, "recipe": "custom", "scenes": [ ... ] },
"edits": [
{ "scene_index": 0, "action": "edit_caption", "value": "The hook is simple" },
{ "scene_index": 2, "action": "regen_visual" }
]
}

A manifest that is missing or belongs to another recipe, or an edit with an unknown scene or action, fails the job; its error says which.

Common Compose fields

FieldUse
recipeRequired. Recipe slug from GET /v1/videos/compose/recipes.
modeplan, render, or edit.
briefTopic, idea, or direction for plan mode.
scriptOptional script text for plan mode.
storyboardRequired for render mode. Usually the completed plan result.
manifest and editsRequired for edit mode.
aspect_ratioCommon values include 9:16, 16:9, and 1:1, depending on recipe support.
scene_countRequested scene count for plan mode.
input_modetopic (default) writes a script from the brief; script reads your text as the narration.
resolutionRender mode: the resolution the scene videos are generated at, such as 720p (default) or 1080p. The options are the recipe’s video model’s resolution parameter on GET /v1/models/{model}. Higher resolutions cost more per scene.
visual_modePlan mode: video, image, or auto (the plan chooses per scene). Defaults to the recipe’s mode.
audio_modePlan mode: voiceover narrates; music makes a montage with no narration, set to music.
aestheticOptional Generation Template look for every scene, such as dark-fantasy or dreamcore; its recommended model generates the scenes.
caption_styleCaption style ID from the recipes endpoint.
musicOptional music direction or preset.
voiceThe narration voice, one of the voice model’s voice options. A value on a render request takes precedence over the storyboard’s.
product_imageOptional product reference image for recipes that accept one.
face_imageOptional face or character reference for recipes that require one.
gameplay_styleOptional gameplay background style when the recipe supports gameplay variants.
model_overridesOptional per-stage model overrides, such as { "visual": "seedance-2-0-pro" }. On gameplay recipes the visual model generates the background video. A voice or visual model on a render request takes precedence over the storyboard’s.

Compose usage and billing

Compose records a parent usage row for the production, plus internal model legs for script, voice, visuals, transcription, music, and assembly when those stages run. The parent row is the customer-facing row returned by the Account Usage API.

curl "https://api.empiriolabs.ai/v1/account/usage?source=compose&limit=20" \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Compose rows use source: "compose" and include structured metadata:

{
"source": "compose",
"model": "custom",
"endpoint": "/v1/videos/compose",
"cost": { "amount": 0, "currency": "USD" },
"metadata": {
"category": "compose",
"compose": {
"recipe": "custom",
"mode": "render",
"phase": "render",
"leg_count": 5,
"total_cost_usd": 0.1832,
"legs": [
{
"stage": "voice",
"model": "inworld-tts-mini",
"cost_usd": 0.012
}
]
}
}
}

A render needs a balance that covers the whole production before it starts; otherwise the job fails with insufficient_credits and nothing is charged.

The production row’s cost.amount is 0: each step is charged on its own row (metadata.compose_leg: true), and total_cost_usd is the sum of those charges. Use metadata.compose.legs for a breakdown of which steps contributed.

Fetch a single template

GET
/v1/templates/:slug
curl https://api.empiriolabs.ai/v1/templates/studio-product-shot
curl https://api.empiriolabs.ai/v1/templates/studio-product-shot \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Returns 404 with code: "template_not_found" if the slug doesn’t exist.

Generate a video with a template

Add template: "<slug>" to a normal /v1/videos/generations call. You must provide whatever the template requires (required_inputs), usually a reference image.

curl https://api.empiriolabs.ai/v1/videos/generations \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": "baseball-stadium",
"image_url": "https://example.com/me.jpg"
}'

Behavior:

  • Model selection: if you don’t pass model, the template’s recommended_model is used. If you do, most templates validate that it is in supported_models and return 400 template_model_unsupported otherwise. Some templates run only on their own model: any other model returns 400 template_model_pinned with param set to model, and the message names the model to use. Leave model out, or set it to that model.
  • Modality check: image templates only apply to /v1/images/generations; video templates only apply to /v1/videos/generations.
  • Prompt blend: your prompt (if any) is combined with the template’s built-in styling so the generated output matches both your request and the effect’s aesthetic. Send a short directional prompt; EmpirioLabs handles the rest.
  • Default params: default_params from the template merge in only for keys you didn’t set explicitly.
  • Required inputs: { "image": true } means the call returns 400 template_missing_image if no image_url / image / images is provided.

Generate an image with a template

curl https://api.empiriolabs.ai/v1/images/generations \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template": "background-swap",
"prompt": "Place this product on a brushed steel studio plinth",
"image": ["https://example.com/product.jpg"]
}'

The response is the same async job envelope as a normal video generation:

{
"job_id": "abc123...",
"status": "processing",
"poll_url": "/v1/jobs/abc123..."
}

Poll GET /v1/jobs/{job_id} until terminal.

Extend a prior video

/v1/videos/generations also accepts extend_from to continue a previous generation. EmpirioLabs handles the prior-clip wiring for you and uses a sensible continuity prompt unless you provide your own.

curl https://api.empiriolabs.ai/v1/videos/generations \
-H "Authorization: Bearer $EMPIRIOLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"extend_from": { "job_id": "<prior_job_id>" }
}'

You can also pass a direct URL:

{ "extend_from": { "video_url": "https://media.empiriolabs.ai/..." } }

Extend can compose with templates:

{
"template": "action-hero",
"extend_from": { "job_id": "<prior>" }
}

Extend works on every video model

Pass extend_from with any supported video model. If you omit model, the extend runs the template’s recommended_model when you also pass template, and seedance-2-0-pro otherwise.

Error codes

HTTPcodemeaning
400template_not_foundthe slug doesn’t match any active template
400template_model_unsupportedthe model you passed isn’t in the template’s supported_models
400template_model_pinnedthe template runs only on its own model. Leave model out, or set it to the model the message names.
400missing_required_parametera video request had no model, template, or extend_from. Add a model.
400template_modality_mismatchthe template modality doesn’t match the generation endpoint
400template_missing_imagethe template requires an image but the body didn’t include one
400template_missing_videothe template requires a reference video but the body didn’t include one
400template_no_modelthe template has no recommended_model and you didn’t pass one
400extend_extraction_failedcouldn’t process the prior video for extend. Try a different model.
400extend_invalid_shapeextend_from was malformed
400extend_no_prior_videothe prior job had no resolvable video URL
404extend_prior_not_foundthe job_id in extend_from was unknown
500extend_frame_upload_failedcouldn’t prepare the prior video for extend. Retry, or try a different model.
400compose_unknown_recipethe recipe slug is not active
400compose_bad_modemode was not plan, render, or edit
400missing_briefplan mode needs brief or script content
400missing_storyboardrender mode needs a storyboard
401unauthorizedthe request was missing a valid API key
402insufficient_creditsyour balance cannot cover the job, or the next step of a Compose production. Add credits and run it again.
503billing_unavailablebilling could not be checked. Retry shortly.
504compose_render_timeoutthe render exceeded the production budget. Try fewer or shorter scenes.