Generations
Create static ads, video ads, UGC ads, and AI model outputs.
POST /generations
Queues one or more generations.
Authentication is required.
Requires generations:write.
curl -X POST https://videotok.app/api/v1/generations \
-H "Authorization: Bearer vt_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: generation-001" \
-d '{...}'
Shared Fields
| Field | Type | Notes |
|---|---|---|
type | string | static_ad, video_ad, ugc_ad, or ai_model. |
prompt | string | User-facing instruction. |
aspect_ratio | string | Common values: 1:1, 9:16, 16:9, 4:5, auto. |
reference_image_urls | string[] | Product, brand, person, scene, style, or first-frame references. |
brand_kit_id | number | Optional brand kit from GET /assets. |
avatar_id | string | Optional avatar from GET /assets. |
preset_id | string | Optional built-in inspiration preset from GET /models. |
custom_reference_inspiration_id | uuid | Optional user-saved reference inspiration. |
request_count | number | 1 to 10. |
idempotency_key | string | Body fallback when no Idempotency-Key header is sent. |
Static Ad Fields
| Field | Type | Notes |
|---|---|---|
template_slug | string | From static_ads[].slug. |
resolution | string | Usually 1K. |
{
"type": "static_ad",
"template_slug": "product-shoot",
"prompt": "Premium ad for a collagen drink.",
"aspect_ratio": "1:1",
"resolution": "1K",
"brand_kit_id": 42,
"request_count": 1,
"idempotency_key": "static-001"
}
Video Ad And UGC Fields
| Field | Type | Notes |
|---|---|---|
template_slug | string | From video_ads[].slug or ugc_ads[].slug. |
duration | number | Must fit the selected quality tier. |
quality_tier | string | Usually high or low. |
source_video_url | string | Optional source clip. |
motion_video_url | string | Optional motion reference when supported. |
audio_url | string | Optional audio reference when supported. |
Video ad:
{
"type": "video_ad",
"template_slug": "motion-graphics",
"prompt": "A fast hook-driven launch ad for an AI note-taking app.",
"aspect_ratio": "9:16",
"duration": 8,
"quality_tier": "high",
"brand_kit_id": 42,
"avatar_id": "avatar_123",
"reference_image_urls": ["https://example.com/product.png"],
"preset_id": "egor",
"idempotency_key": "video-001"
}
UGC ad:
{
"type": "ugc_ad",
"template_slug": "ugc-product-video",
"prompt": "Natural creator testimonial for a skincare serum.",
"aspect_ratio": "9:16",
"duration": 8,
"quality_tier": "high",
"avatar_id": "avatar_123",
"reference_image_urls": ["https://example.com/product.png"],
"idempotency_key": "ugc-001"
}
AI Model Fields
| Field | Type | Notes |
|---|---|---|
model_slug | string | From ai_models[].slug. |
variant_id | string | From ai_models[].variants[].id. |
source_video_url | string | For edit or video-to-video variants. |
motion_video_url | string | For motion-control variants. |
audio_url | string | For audio-driven variants. |
generate_audio | boolean | For variants that support generated audio. |
Image model:
{
"type": "ai_model",
"model_slug": "nano-banana-2",
"variant_id": "image",
"prompt": "Minimal e-commerce hero image for white sneakers on concrete.",
"aspect_ratio": "1:1",
"resolution": "1K",
"idempotency_key": "model-image-001"
}
First-frame / last-frame model:
{
"type": "ai_model",
"model_slug": "veo",
"variant_id": "first-frame-last-frame",
"prompt": "A cinematic product reveal from packed box to final table setup.",
"aspect_ratio": "9:16",
"duration": 8,
"reference_image_urls": [
"https://example.com/first-frame.png",
"https://example.com/last-frame.png"
],
"idempotency_key": "model-video-001"
}
GET /generations/{id}
Returns generation status and the final asset URL.
Requires generations:read or generations:write.
curl https://videotok.app/api/v1/generations/9f9f2d49-3c9c-4a45-a16d-c0d7d0c8b0ce \
-H "Authorization: Bearer vt_live_..."
Do not retry a partial batch with a new idempotency key unless the user wants additional outputs.