Skip to main content
POST
Create a talking avatar job

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Unique key for safe retries of job creation requests.

Required string length: 8 - 128

Body

application/json

Talking-avatar request. Lip-syncs a still portrait to either a generated script (TTS) or an existing audio file.

Pricing: 3 credits per second, minimum 5 seconds. +5 credits when product_placement=true. For script mode, duration ≈ len(script) / 10 seconds, and script must be at least 100 characters (enforced server-side).

avatar_image_url
string<uri>
required

Hosted portrait image (png/jpg/jpeg/webp, ≤ 50 MB).

script
string
required

Script for mode=script. Min 100 chars (server-enforced).

Required string length: 100 - 8192
mode
enum<string>
default:script

• script — generate speech from script (default). • audio — lip-sync to the provided audio_url.

Available options:
script,
audio
audio_url
string<uri>

Hosted audio URL for mode=audio (mp3/wav/m4a, ≤ 50 MB).

voice_id
string | null

Optional library or custom voice ID. If omitted in mode=script, the first voice in your library catalog is used.

product_placement
boolean
default:false

When true (with product_image_url), fuses a product into the shot. Adds 5 credits.

product_image_url
string<uri>

Required when product_placement=true.

background_url
string<uri> | null

Optional hosted background image URL.

Response

Talking avatar job accepted.

id
string
required
object
enum<string>
required
Available options:
image_generation_job,
video_generation_job,
talking_avatar_job
status
enum<string>
required
Available options:
queued,
processing,
completed,
failed,
canceled
credits_reserved
integer
required
assets
object[]
required
created_at
string<date-time>
required
progress_percent
integer | null
Required range: 0 <= x <= 100
credits_used
integer | null
credits_refunded
integer
default:0
request
object
failure_code
string | null
failure_message
string | null
updated_at
string<date-time> | null
completed_at
string<date-time> | null
failed_at
string<date-time> | null