Skip to content
Log in
Developer API
Get your keyGet a key

Reference · Video

POST/avatars

Make a talking avatar clip, or lip-sync a clip to a voice

A talking video, as the Avatars page makes it: a cast member (GET /api/v1/cast) lip-synced to a voiceover — or, with kind "revoice", footage of a real person lip-synced to new words. The words go in one of three ways: typed (script), voiced first in the cast member’s own voice — or voiceId’s — and lip-synced, as the page does in one press; a voiceover take of theirs (voiceTakeId, from POST /api/v1/voiceovers); or a recording they uploaded (recordingKey, with whoseRecording). Priced by the seconds of voiceover, on the model (GET /api/v1/models, studio "avatars"); typed words are quoted as their voice plus the most the clip can cost, and charged the take’s real length. It comes back as a job (kind "avatar") to follow with GET /api/v1/jobs/{jobId}.

Key needs
create · Make things and spend credits
Price it first
POST /avatars/quote · free
Answers
A job to follow
Request
curl -X POST https://vessero.com/api/v1/avatars \
  -H "Authorization: Bearer $VESSERO_API_KEY" \
  -H "Idempotency-Key: 47f8f6f5-ea00-4fb1-925f-76aac956a0ec" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmCredits": 1
  }'
Response202 Accepted
{
  "object": "job",
  "id": "avatar.8f1c2d3e-4b5a-4789-8abc-def012345678",
  "kind": "avatar",
  "status": "working",
  "stage": "Queued",
  "files": [],
  "credits": 58,
  "url": "/api/v1/jobs/avatar.8f1c2d3e-4b5a-4789-8abc-def012345678"
}
POST/avatars/quoteFree

The same body without confirmCredits. It answers the price and your balance, and runs nothing.

Header

  • Idempotency-KeystringYour id for this request: 8–64 letters, digits, - or _. A repeat within 10 minutes gets the first answer back and never runs twice. Use the same one for the quote and the run.
  • Preferstringwait=N (up to 60): hold the answer up to N seconds while the job is made, within 80 seconds for the whole call.

Body

  • kindstringavatar (the default): a cast member speaks. revoice: footage of a real person (clipKey) says new words.avatarrevoice
  • castMemberIdstringAn avatar’s speaker: a cast member id from GET /api/v1/cast.
  • modelstringAn avatar’s talking model id, from GET /api/v1/models (studio "avatars").
  • stylestringAn avatar’s look: selfie (a phone at arm’s length, the default), studio, or cinematic.selfiestudiocinematic
  • scriptstringThe words to say, typed (up to 5,000 characters): voiced first in the cast member’s own voice, or voiceId’s, then lip-synced. Give this, voiceTakeId or recordingKey.
  • voiceIdstringWith script: the voice to read them in, from GET /api/v1/voices (a cast member’s own is its voiceId in GET /api/v1/cast). Default: the speaker’s own voice, else the default voice.
  • voiceTakeIdstringOr the words as a voiceover take of theirs: the id POST /api/v1/voiceovers returns, or the one a voiced script kept.
  • recordingKeystringOr the words as a recording they uploaded (MP3 or WAV): a storage key from POST /api/v1/files or POST /api/v1/library/use, or an https link to the file (brought into their Uploads first). Not a copy of something made in Vessero: a take made here goes in as voiceTakeId.
  • whoseRecordingobject · kind ai-voice | voiceWith recordingKey: whose voice it is, as the person says — {kind: "ai-voice"}, or {kind: "voice", name, agreed} for a real person’s.
  • clipKeystringRevoice: the footage, a clip (MP4 or MOV) of one person speaking: a storage key from POST /api/v1/files or POST /api/v1/library/use, or an https link to the file (brought into their Uploads first).
  • personInClipobjectRevoice: the real person in the footage, named, with their permission.
    • namestringrequiredTheir full name, as the person gives it.
    • agreedbooleantrue only once the person has read the statement the quote gives for this name and agreed to it. Leave it out when asking for the price; the run is refused without it.
  • modestringRevoice: lite (one person facing the camera, the default) or basic (scene cuts; finds who is speaking).litebasic
  • confirmCreditsintegerrequiredThe price you agree to, in credits: the credits its quote gave. It runs at that price, or at a lower one when that figure was quoted for this Idempotency-Key; above the price now, nothing runs (409 price_changed). Left out, nothing runs and the error carries the quote.
  • webhookUrlstring · httpsAn https address to POST the job to once it is done or has failed, signed (see Webhooks).

Answers

  • 202jobStarted: follow the job, or wait for its webhook.
  • 200jobA job that ended at once: done, or failed (see error and charged).
  • 400confirm_credits_requiredA run that spends needs confirmCredits: the quote is in details.
  • 402insufficient_creditsThe account has too few credits for this.
  • 409price_changedThe price is above the confirmCredits sent: nothing ran; the new quote is in details.
  • 422content_refusedThe content check refused it.
  • 429daily_cap_reachedThe key’s daily credit cap would be passed: see Retry-After.
Next in VideoPOST/avatars/quote