Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Lip-sync a still avatar image to a script or to an existing audio file.
| Method | Endpoint | Purpose |
|---|---|---|
POST | /v1/talking-avatars | Create a talking-avatar job. |
GET | /v1/talking-avatars | List recent talking-avatar jobs. |
GET | /v1/talking-avatars/{job_id} | Get one talking-avatar job. |
| Mode | What it does | Required fields |
|---|---|---|
script (default) | Generate speech from text and lip-sync the avatar. | avatar_image_url, script |
audio | Lip-sync the avatar to an existing audio file. | avatar_image_url, audio_url |
| Field | Type | Required | Notes |
|---|---|---|---|
avatar_image_url | string | Yes | Hosted portrait image URL — png/jpg/jpeg/webp, up to 50 MB. Upload local files via POST /v1/assets first. |
mode | string | No | script (default) or audio. Anything else is rejected. |
script | string | Yes when mode=script | Minimum 100 characters, max 8192. Duration estimate = len(script) / 10 seconds. |
audio_url | string | Yes when mode=audio | Hosted audio URL — mp3/wav/m4a, up to 50 MB. |
voice_id | string | No | Library or custom voice ID. If omitted in script mode, the first voice in your library catalog is used. |
product_placement | boolean | No | Set true AND pass product_image_url to fuse a product into the shot. Adds 5 credits. |
product_image_url | string | No | Hosted product image URL. Used only when product_placement=true. |
background_url | string | No | Optional hosted background image URL. |
Idempotency-Key is required on every POST /v1/talking-avatars.The 100-character minimum for script is enforced server-side — shorter
scripts are rejected with invalid_request.script and audio_url cannot both be supplied. If mode=script but you
only pass audio_url, the request is auto-promoted to mode=audio.product_placement=true.# 1) Upload the avatar portrait
curl https://api.adskull.io/v1/assets \
-H "Authorization: Bearer $ADSKULL_API_KEY" \
-F asset_type=image \
-F file=@./host.png
# 2) Generate the talking avatar
curl https://api.adskull.io/v1/talking-avatars \
-H "Authorization: Bearer $ADSKULL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: avatar-script-001" \
-d '{
"avatar_image_url": "https://cdn.adskull.io/uploads/host.png",
"mode": "script",
"voice_id": "ahmed",
"script": "Welcome to AdSkull. In the next thirty seconds, I will show you how a single prompt can produce a finished, full-audio ad ready for TikTok, Reels, and YouTube Shorts."
}'
curl https://api.adskull.io/v1/talking-avatars \
-H "Authorization: Bearer $ADSKULL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: avatar-audio-001" \
-d '{
"avatar_image_url": "https://cdn.adskull.io/uploads/host.png",
"mode": "audio",
"audio_url": "https://cdn.adskull.io/uploads/voiceover.mp3"
}'
curl https://api.adskull.io/v1/talking-avatars \
-H "Authorization: Bearer $ADSKULL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: avatar-product-001" \
-d '{
"avatar_image_url": "https://cdn.adskull.io/uploads/host.png",
"mode": "script",
"voice_id": "ahmed",
"script": "Meet the new AdSkull One — it produces a complete ad in under sixty seconds from a single prompt. Here is how it transforms your campaign workflow today.",
"product_placement": true,
"product_image_url": "https://cdn.adskull.io/uploads/product.png"
}'
{
"id": "job_01HXAV...",
"object": "talking_avatar_job",
"status": "completed",
"credits_reserved": 45,
"credits_used": 45,
"completed_at": "2026-05-17T12:04:00Z",
"assets": [
{
"id": "asset_01HX...",
"type": "video",
"url": "https://cdn.adskull.io/generated/avatar.mp4",
"mime_type": "video/mp4",
"duration_seconds": 15,
"width": 1080,
"height": 1920,
"expires_at": "2026-05-18T12:04:00Z"
}
]
}
| HTTP | Code | When it happens |
|---|---|---|
| 400 | invalid_request | Script shorter than 100 chars, missing required field for mode, unsupported file format. |
| 401 | unauthorized | API key missing or invalid. |
| 402 | insufficient_credits | Not enough credits. |
| 413 | payload_too_large | Avatar / audio / product file > 25 MB. |
| 422 | content_policy_violation | Image, audio, or script not allowed. |
| 429 | rate_limited | Too many requests. |
| 503 | temporarily_unavailable | Provider capacity temporarily unavailable. |