Templates API

Save reusable job configurations as templates. Templates store persona, model, voice, script, and quality settings so you can create consistent videos without re-entering the same parameters. Max 20 templates per account.

How Templates Work

Templates store all job configuration fields except product-specific data (product_name, product_image_url). Load a template into your job creation form, provide the product details, and submit. All config fields are optional — only include the settings you want to standardize.

List Templates

Retrieve all job templates for your account, sorted by default first, then by most used and most recently updated.

GET/api/v1/templates

• Returns a bare array (not paginated).

• Sorted by: is_default DESC, use_count DESC, updated_at DESC.

• Only returns templates owned by the authenticated tenant.

Parameters

Parameter Type Description

Parameter	Type	Description
`limit`	integer Default: 50	Max results. 1–100

limit

integer

Default: 50

Max results.

1–100

Request Example

curl -X GET "https://api.u-gen.ai/api/v1/templates?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

Create Template

Save a job configuration as a reusable template. Returns HTTP 201 Created.

POST/api/v1/templates

• Maximum 20 templates per account.

• Setting is_default to true automatically unsets the previous default.

• Only non-null config fields are stored — omitted fields are excluded.

Body

Parameter	Type	Description
`name`REQ	string	Display name for the template. 1–100 characters
`description`	string	Optional description. Max 500 characters
`config`REQ	TemplateConfig	Job configuration object. All fields are optional — see Config Fields below.
`is_default`	boolean Default: false	Set as the default template. Only one default per account.

Request Example

curl -X POST https://api.u-gen.ai/api/v1/templates \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quick Demo - Tech",
    "description": "Fast tech product demos with energetic delivery.",
    "config": {
      "persona_id": "09d3a33a-3eb0-480a-80df-0c64dbf7c98f",
      "video_model": "kling3_std",
      "segment_count": 2,
      "output_aspect_ratio": "9:16",
      "interaction_mode": "display_static",
      "caption_style": "tiktok_karaoke",
      "captions_enabled": true,
      "music_enabled": true,
      "qai_enabled": false
    },
    "is_default": false
  }'

Update Template

Update a template's name, description, config, or default status. Only provided fields are changed.

PATCH/api/v1/templates/{template_id}

• Returns 404 if the template does not exist or belongs to another tenant.

• Config is replaced entirely, not merged. Include all desired fields in the update.

• At least one field must be provided or a 400 error is returned.

Path

Parameter	Type	Description
`template_id`REQ	string (UUID)	The template identifier.

Body

Parameter	Type	Description
`name`	string	Updated name. 1–100 characters
`description`	string	Updated description. Max 500 characters
`config`	TemplateConfig	Updated config. Replaces the entire config object.
`is_default`	boolean	Set or unset as default.

Request Example

curl -X PATCH https://api.u-gen.ai/api/v1/templates/f1e2d3c4-b5a6-7890-abcd-ef1234567890 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quick Demo - Tech v2",
    "config": {
      "segment_count": 3,
      "music_mood": "energetic"
    }
  }'

Delete Template

Permanently delete a job template. Existing jobs are not affected.

DELETE/api/v1/templates/{template_id}

• Returns 204 No Content on success (no response body).

• Returns 404 if the template does not exist or belongs to another tenant.

Path

Parameter	Type	Description
`template_id`REQ	string (UUID)	The template identifier.

Request Example

curl -X DELETE https://api.u-gen.ai/api/v1/templates/f1e2d3c4-b5a6-7890-abcd-ef1234567890 \
  -H "X-API-Key: YOUR_API_KEY"

Track Template Usage

Increment the use_count for a template. Call this when a template is loaded into a form.

POST/api/v1/templates/{template_id}/use

• Returns 204 No Content (no response body).

• The use_count is used for sorting — most-used templates appear first in the list.

Path

Parameter	Type	Description
`template_id`REQ	string (UUID)	The template identifier.

Request Example

curl -X POST https://api.u-gen.ai/api/v1/templates/f1e2d3c4-b5a6-7890-abcd-ef1234567890/use \
  -H "X-API-Key: YOUR_API_KEY"

Config Fields Reference

All fields in the config object are optional. Only include settings you want the template to standardize. Product-specific fields (product_name, product_image_url) are excluded from templates.

Field	Type	Description
`persona_id`	string (UUID)	Default persona identifier
`video_model`	string	kling3_std (default), kling3_pro, kling3_4k
`segment_count`	integer	Number of video segments (1–10)
`segment_duration`	integer	Per-segment duration in seconds. Kling 3.0: 3–10
`output_aspect_ratio`	string	9:16, 16:9, Auto, 1:1 (Kling)
`interaction_mode`	string	holdable, display_static, wearable, surface_interactive. consumable and apply_to_body are still accepted for existing integrations but are no longer recommended.
`language`	string	ISO 639-1 code (default: en)
`video_resolution`	string	standard, 1080p, 4k
`keyframe_resolution`	string	1k, 2k, 4k
`caption_style`	string	tiktok_karaoke, tiktok_highlight, mrbeast_karaoke, neon_karaoke, minimal_karaoke, custom
`captions_enabled`	boolean	Generate captions
`music_enabled`	boolean	Background music
`music_mood`	string	Music mood filter (e.g., upbeat, cinematic)
`music_volume`	float	Volume level (0.05–0.30)
`custom_music_id`	string (UUID)	Custom uploaded music track ID
`script_structure`	string	Script structure preset
`script_tone`	string	Script tone (conversational, professional, etc.)
`key_selling_points`	string[]	Up to 5 product selling points
`cta_text`	string	Call-to-action text (max 100 chars)
`environment_description`	string	Custom scene/environment description
`qai_enabled`	boolean	AI Quality Assurance toggle
`qai_mode`	string	strict, standard, lenient
`max_retries_keyframe`	integer	Max keyframe retries (0–5)
`max_retries_video`	integer	Max video retries (0–5)
`human_review`	string	off, anchor_only, all
`apply_brand_kit`	boolean	Apply brand logo watermark
`voice_similarity_boost`	float	ElevenLabs similarity (0.0–1.0)
`voice_stability`	float	ElevenLabs stability (0.0–1.0)

Default Template

Only one template can be the default per account. Setting is_default: true on create or update automatically unsets the previous default. The default template is always listed first.