Reference Inspirations
Save and reuse reference media for generation.
Reference Types
Built-in inspiration presets come from GET /models and are selected with preset_id.
Workspace reference inspirations are created by the user, API, or MCP and selected with custom_reference_inspiration_id.
Suggested Storage Flow
When an agent receives images or video in chat:
- Upload or pass the media to
GET /reference-inspirations?suggest_targets=true. - Show the suggested template targets to the user.
- Ask which template should store the reference.
- Call
POST /reference-inspirations. - Use the returned reference id in future generations.
GET /reference-inspirations?suggest_targets=true
Suggests where uploaded media should be saved.
Requires generations:read or generations:write.
curl "https://videotok.app/api/v1/reference-inspirations?suggest_targets=true&media_kind=image&description=yellow%20restaurant%20ad" \
-H "Authorization: Bearer vt_live_..."
{
"object": "reference_template_target_suggestions",
"media_kind": "image",
"image_count": 0,
"has_video": false,
"suggestions": [
{
"template_slug": "motion-graphics",
"template_category": "video-templates",
"label": "Motion graphics",
"accepts_media_kinds": ["image", "video"],
"score": 6,
"reason": "Good match for video ad references."
}
],
"next_step": "Ask the user which template target to use, then call create_reference_inspiration with that template_slug and template_category."
}
POST /reference-inspirations
Saves uploaded reference media to the selected template target.
Authentication is required.
Requires generations:write.
curl -X POST https://videotok.app/api/v1/reference-inspirations \
-H "Authorization: Bearer vt_live_..." \
-H "Content-Type: application/json" \
-d '{
"template_slug": "motion-graphics",
"template_category": "video-templates",
"media_kind": "image",
"visibility": "private",
"label": "Yellow restaurant ad",
"image_urls": ["https://example.com/reference.png"]
}'
Inline base64 upload is also supported:
{
"template_slug": "product-shoot",
"template_category": "static-ads",
"media_kind": "image",
"label": "Clean supplement reference",
"images": [
{
"filename": "reference.png",
"content_type": "image/png",
"data": "iVBORw0KGgo..."
}
]
}
Fields
| Field | Type | Notes |
|---|---|---|
template_slug | string | Target template. |
template_category | string | static-ads, video-templates, or slideshow-carousel. |
media_kind | string | image, slideshow, or video. |
visibility | string | private or public. Public references require review. |
label | string | User-facing label. |
image_urls | string[] | Existing public image URLs. |
images | object[] | Inline base64 images. |
images[].filename | string | Original filename for base64 upload. |
images[].content_type | string | Optional MIME type. |
images[].data | string | Base64 image data or data URL. |
video_url | string | Required when media_kind is video. |
GET /reference-inspirations
Lists saved references and valid template targets.
Requires generations:read or generations:write.
curl https://videotok.app/api/v1/reference-inspirations \
-H "Authorization: Bearer vt_live_..."
GET /reference-inspirations?recommend=true
Recommends saved references for a template.
Requires generations:read or generations:write.
curl "https://videotok.app/api/v1/reference-inspirations?recommend=true&template_slug=motion-graphics&template_category=video-templates&media_kind=image" \
-H "Authorization: Bearer vt_live_..."