Get API key

Core

Media & assets

The pieces you attach to a video — avatars, voices, brand kits, and your own files.

Avatars

GET/v1/avatars

Browse the avatar catalogue and your own avatars.

Query parameters
viewstringoptional
characters (default, grouped) or catalogue (flat list).
searchstringoptional
Filter by name.
genderstringoptional
male, female, or unspecified.
limitintegeroptional
How many to return (1–200).
Returns

A list of avatars; owned holds the ones you created.

POST/v1/avatars

Generate a new avatar. Training runs in the background.

Parameters
kindstringrequired
"prompt" (designed from a text description) or "photo" (built from a photo).
namestringrequired
A label for your avatar.
promptstringoptional
For kind: "prompt" — describe the person.
file_urlstringoptional
For kind: "photo" — a public https photo (from uploads).
consentbooleanoptional
Required true for kind: "photo" (real-person consent).
Returns

An avatar with status: "processing". Poll it below until ready, then use its id as an auto-mode avatar_id.

GET/v1/avatars/{id}

Check avatar training status. Use it in videos once ready is true.

Voices

GET/v1/voices

List 100+ voices.

Query parameters
languagestringoptional
e.g. English.
genderstringoptional
Filter by gender.
searchstringoptional
Filter by name.
limitintegeroptional
1–200, default 50.
POST/v1/voices/speech

Generate a short TTS sample so you can preview a voice. (Cloning is not available via the API.)

Parameters
voice_idstringrequired
A voice id from the list above.
textstringrequired
What to say. Up to 300 characters.
Returns

An audio_url and duration_seconds.

Brand kits

A brand kit is a logo, colors, fonts, motion style and identity. Apply one to auto videos with brand_kit_id.

POST/v1/brand-kits

Create a brand kit.

Parameters
namestringrequired
Brand name.
logo_urlstringoptional
Public logo image (from uploads).
primary_colorstringoptional
Hex, e.g. #7C5CFF. Also secondary_color, accent_color.
title_fontstringoptional
Font names — also body_font.
motion_stylestringoptional
elevated, friendly, minimal, professional, or playful.
brand_identitystringoptional
A short description of the brand's voice and audience.
POST/v1/brand-kits/from-url

Draft a brand kit automatically from a website. Returns an unsaved draft to review, then POST /v1/brand-kits to save.

Parameters
urlstringrequired
Your public website url.
GET/v1/brand-kits

List your brand kits.

DELETE/v1/brand-kits/{id}

Delete a brand kit.

Uploads — get a public URL

POST/v1/uploads

Get a presigned upload URL and the public URL it becomes. Use it for image-to-video inputs, avatar photos, and brand logos.

Parameters
filenamestringrequired
e.g. frame.png.
content_typestringrequired
e.g. image/png.
Returns

An upload_url (PUT your bytes there) and a public_url. Use public_url as image_url, first_frame_url, an avatar file_url, or a brand logo_url.

Example
upload a file
# 1. get a presigned URL
curl https://api.vivideo.ai/v1/uploads \
  -H "Authorization: Bearer $VIVIDEO_API_KEY" \
  -d '{"filename":"frame.png","content_type":"image/png"}'
# → { "upload_url": "...", "public_url": "https://vivideocdn.com/uploads/..." }

# 2. PUT the bytes
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @frame.png

# 3. use public_url as image_url in a manual video

Assets — for auto-mode references

Auto-mode file_asset_ids reference an asset (a file registered with the avatar engine). Create one, upload the bytes, complete it, then pass its asset_id.

POST/v1/assets

Start an asset upload.

Parameters
filenamestringrequired
e.g. reference.png.
content_typestringrequired
e.g. image/png.
size_bytesintegerrequired
File size in bytes.
Returns

id, asset_id, an upload_url and upload_headers. PUT the bytes to upload_url, then call complete below.

POST/v1/assets/{id}/complete

Finalize the asset after uploading its bytes. Returns the asset, ready to use as a file_asset_ids entry.

GET/v1/assets

List your assets.

DELETE/v1/assets/{id}

Delete an asset.

i
Two kinds of file id. public_url (from uploads) is a plain URL that works anywhere a URL is expected. asset_id (from assets) is what the auto pipeline references via file_asset_ids.
← Previous
Create videos
Machine-readable: interactive reference · openapi.yaml · llms-api.txt. Base URL https://api.vivideo.ai.