Generation Templates

Templates are pre-curated “creative effect” recipes for /v1/images/generations and /v1/videos/generations. Each template ships a recommended model, a list of supported models, default parameters, and required input rules. Pass template: "<slug>" in the request body and EmpirioLabs applies the effect with whatever else you provide, picks the best supported model for you, and forwards the call to the worker.

The same template catalog powers the Templates button in the playground.

List templates

1
curl https://api.empiriolabs.ai/v1/templates \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json"

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

1
curl https://api.empiriolabs.ai/v1/videos/templates \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json"

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

1
{
2
  "object": "list",
3
  "template_count": 11,
4
  "data": [
5
    {
6
      "slug": "baseball-stadium",
7
      "display_name": "Stadium",
8
      "category": "viral",
9
      "description": "Customer-facing description shown in the playground card.",
10
      "recommended_model": "kling-o3",
11
      "supported_models": ["kling-o3"],
12
      "default_params": { "aspect_ratio": "16:9", "duration": 10 },
13
      "required_inputs": { "image": true, "min_images": 1, "max_images": 1 },
14
      "cover_image_url": "https://media.empiriolabs.ai/assets/template-posters/baseball-stadium.jpg",
15
      "preview_video_url": "https://media.empiriolabs.ai/assets/template-previews/baseball-stadium.mp4",
16
      "modality": "video",
17
      "is_featured": true,
18
      "display_order": 10
19
    }
20
  ]
21
}

List image templates

1
curl https://api.empiriolabs.ai/v1/images/templates \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json"

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

Fetch a single template

1
curl https://api.empiriolabs.ai/v1/templates/studio-product-shot \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json"

$
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. Templates with metadata.force_recommended_model: true are pinned to recommended_model for effect fidelity.
• 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:

1
{
2
  "job_id": "abc123...",
3
  "status": "processing",
4
  "poll_url": "/v1/jobs/abc123..."
5
}

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:

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

Extend can compose with templates:

1
{
2
  "template": "action-hero",
3
  "extend_from": { "job_id": "<prior>" }
4
}

Extend works on every video model

Pass extend_from with any supported video model. If you omit model, EmpirioLabs picks a sensible default for the extend.

Error codes