Image + audio → talking avatar
One face image (URL) and one audio track (URL) produce a lip-synced talking-head video. Long audio is handled with multi-segment continuation.
CatalogLatency Asynchronous. Generation is GPU-heavy — minutes, scaling with audio length. Compose is faster. Async true Rate Limit Per API key Max Input Generate: one face image + one audio track. Compose: two video URLs.
cn8/avatar
Two capabilities:
Learn more about Avatar (Beta) Videoasync (job)Instant previewavatarvideogeneration
Input
string
Drag & drop, paste a URL, or choose a fileImage — JPG, PNG, WebP or GIF
Public URL of the face image (camelCase).
string
Drag & drop, paste a URL, or choose a fileAudio — MP3, WAV, OGG or M4A
Public URL of the audio track to lip-sync (camelCase).
Instant sample preview — no cost, no account. Sign up free to run with your own input.
Result
Completed Instant previewJson
{
"status": "accepted",
"message": "Job queued for processing",
"job": {
"id": "550e8400-...",
"status": "queued",
"service": "avatar-generate",
"created_at": "..."
}
}Example response from this endpoint's API reference. Sign in to run it on your own input.
This request costs 10 credits per second.
Overview
Two capabilities:
Avatar Generate (avatar-generate): give it a face image and an audio track, and it produces a talking-avatar video (LongCat pipeline) — the face is animated with lip-sync matching the audio.
Avatar Compose (avatar-compose): overlay a greenscreen avatar video onto a main video as a picture-in-picture — chroma-key removes the green background and the avatar is blended into a corner of the main video.
Both are asynchronous gateway jobs: submit, get a job id, poll GET /v2/jobs/{job_id}.
Key capabilities
Greenscreen PiP compose
Chroma-key a greenscreen avatar clip and blend it over a main video — position/scale/edge controls included.
Standard gateway job flow
Both services return a job id; poll GET /v2/jobs/{job_id} until completed and read result_data.data.output_url.
Live progress while it runs
A poll carries a progress block: phase while the job waits for a GPU, then segment/total/percent once frames are being generated. The job reads queued until generation actually starts, so processing always means work on the card.
Up to five minutes per request
One request generates at most five minutes of video; the audio length is measured on submit, so an over-long request is refused in seconds rather than after a GPU has been started. Longer material is split and joined with avatar-compose.
Estimated time to finish
Every poll answers with progress.estimated_finish_at — when the job is expected to be done — sized from the GPU the job is actually running on and narrowed as segments complete. The audio length is measured on submit, so no extra parameter is needed.
Idempotent submits
Submits are idempotent automatically — the gateway request id is used as the key, so a retried request returns the existing job instead of starting a second GPU run.
Input & output
input
Generate: imageUrl + audioUrl. Compose: mainVideoUrl + avatarVideoUrl + chroma/blend controls.
JSON body
output
A job id right away; when the job completes, result_data.data.output_url carries the finished MP4 (presigned URL).
JSON (job)Video URL (in result_data)
Guides & tips
Typical pipeline: generate → compose
- 1
avatar-generatewith a face image + narration audio → talking-avatar MP4 (greenscreen-style head). - 2
avatar-composewith your main video asmainVideoUrland the generated avatar asavatarVideoUrl
→ the avatar appears as a picture-in-picture presenter over your content. Retries are safe on both calls — idempotency is handled by the gateway, so a repeated submit never starts a duplicate GPU job.
Chroma-key tuning (compose)
- Green fringes around the avatar → raise
erosion(up to 5) orsimilarityslightly. - Hard/jagged edges → raise
blur(up to 8) orblend. - Avatar too large/small → adjust
areaScale(0.30 = 30% of the frame area).
Specs
Schema
Request body
imageUrlrequiredstringPublic URL of the face image (camelCase).
audioUrlrequiredstringPublic URL of the audio track to lip-sync (camelCase).
num_segmentsintegerOptional cap on generation segments (1-64). Leave unset to let the pipeline decide from the audio length.
expected_durationnumberLength of your audio in seconds. Not needed to generate — we measure the audio ourselves — but sending it makes the credit reservation match the real bill. The limit is 300 seconds of audio per request.
Pricing
Generation is billed per second of output video plus a fixed per-request fee; the other two services are flat.
| Service | Unit | Price |
|---|---|---|
| Avatar Generate | second | 250 credits per request + 10 credits per second of output |
| Avatar Compose | item | 20 credits |
| Avatar Image Evaluate | item | 2 credits |
Failed jobs are not billed.
Output length equals the length of the audio you send, so you can work out the cost before you call.
The fixed per-request fee covers loading the model onto a dedicated GPU — that work is the same whether the clip is three seconds or three minutes.
For clips shorter than about 30 seconds, Avatar Generate (Cloud) is cheaper; above that this service is both cheaper and the only option, since the cloud models cap out at 60 seconds.