The Image Avatar endpoint uses an uploaded portrait image, an avatar model, and a voice source to generate a video. The image must first be uploaded through the image upload endpoint to obtain an img_id. The voice can come from uploaded finished audio, a built-in TTS voice, or a custom TTS voice.

API-based Image Avatar

Create an Image Avatar: Image Avatar API Documentation

Upload an image: Upload Image API Documentation

Upload finished audio or a voice sample: Upload Video & Audio API Documentation

Query TTS voices: Get Speech (Lipsync) TTS List API Documentation

Create a custom voice: Create Custom Voice API Documentation

Delete a custom voice: Delete Custom Voice API Definition

Query video status: Get Video Generation Status API Documentation

Prerequisites

Before you begin, make sure you have:

A valid PixVerse API key;

A unique Ai-Trace-Id for each request;

An img_id returned by the image upload endpoint;

One of the following two voice sources:

A finished-audio media_id returned by the media upload endpoint;

A TTS script and a valid speaker_id.

The image upload endpoint supports:

A local image file uploaded through image;

An image URL submitted through image_url.

Both methods are used only to obtain an img_id. You cannot pass an image file or image URL directly to the Image Avatar generation endpoint. The image upload endpoint supports png, webp, jpeg, and jpg files up to 20MB and within 10000px.

Quick Start

1. Upload an Image and Obtain img_id

2. Prepare the Voice

3. Create an Image Avatar Task

4. Query the Generation Status and Get the Video

5. Delete a Custom Voice You No Longer Need (Optional)

Step-by-Step Guide

Step 1: Upload an Image

Call the Upload Image API and submit the image through either of the following fields:

Field	Type	Usage Rule
image	binary	Use when uploading a local image file
image_url	string	Use when uploading through an image URL

Use either image or image_url, but not both. Regardless of which method you use, the next step uses only the Resp.img_id returned by the endpoint.

Step 2: Prepare the Voice

An Image Avatar task supports two voice sources:

Voice Source	Request Fields	Processing Rule
Uploaded finished audio	`audio_media_id`	Uses the finished audio directly to drive lip movement; TTS is not performed
TTS	`lip_sync_tts_content` + `lip_sync_tts_speaker_id`	Uses the selected built-in or custom voice to read the script and drive lip movement

The voice fields must follow these rules:

Use either audio_media_id or lip_sync_tts_content, but not both;

If neither is provided, the endpoint returns a missing voice source error;

If both are provided, the endpoint returns a voice source conflict error;

When using TTS, lip_sync_tts_content must contain 30–200 characters;

lip_sync_tts_speaker_id can be a valid built-in voice ID, a custom voice ID, or auto to use the default voice;

If the voice does not exist or the current account cannot access it, the endpoint returns a parameter error.

Step 3: Create an Image Avatar Task

Endpoint:

Headers:

Field	Type	Required	Description
API-KEY	string	Yes	API authentication
Ai-Trace-Id	string	Yes	Use a unique value for each request
Content-Type	string	Yes	Must be `application/json`

Request Body:

Field	Type	Requirement	Description
img_id	int64	Required	Image resource ID returned by the image upload endpoint; only one image is supported
quality	string	Required	Currently supports `360p`, `540p`, `720p`, and `1080p`
prompt	string	Optional	Describes the person's movement, pose, expression, or other visual requirements
audio_media_id	int64	Conditionally required	Uploaded finished-audio `media_id`; use either this field or `lip_sync_tts_content`
lip_sync_tts_content	string	Conditionally required	TTS script containing 30–200 characters; use either this field or `audio_media_id`
lip_sync_tts_speaker_id	string	Conditionally required	Built-in or custom voice ID used for TTS; `auto` is also supported
webhook_id	string	Optional	Uses a webhook already configured on the platform

Use Uploaded Finished Audio

{
  "img_id": 1233333,
  "quality": "720p",
  "prompt": "The person keeps both hands folded and remains still.",
  "audio_media_id": 23424143
}

Use a Built-in or Default TTS Voice

{
  "img_id": 1233333,
  "quality": "720p",
  "prompt": "The person keeps both hands folded and remains still.",
  "lip_sync_tts_content": "Good evening, everyone.",
  "lip_sync_tts_speaker_id": "auto"
}

Use a Custom TTS Voice

{
  "img_id": 1233333,
  "quality": "720p",
  "prompt": "The person keeps both hands folded and remains still.",
  "lip_sync_tts_content": "Good evening, everyone.",
  "lip_sync_tts_speaker_id": "speaker_custom_123"
}

Do not pass audio_media_id in this case. The voice sample is used only when creating the custom voice. The Image Avatar task references only the speaker_id returned by the custom voice creation endpoint or TTS voice list endpoint.

Successful response fields:

Field	Type	Description
ErrCode	int	`0` indicates success
ErrMsg	string	Error message
Resp.video_id	int64	Generation task ID
Resp.credits	int	Credits consumed or estimated for this task

Step 4: Query the Status and Get the Video

Call the Get Video Generation Status API:

status	Meaning	Action
1	Generation succeeded	Use `Resp.url` to access the video
5	Generation in progress	Continue polling
7	Content moderation failed	Stop polling
8	Generation failed	Stop polling

Custom Voice Lifecycle

Upload a sample: Call the media upload endpoint and obtain the sample audio's Resp.media_id. The sample audio must be shorter than 30 seconds.

Create a voice: Call POST /openapi/v2/video/tts_speaker, pass the sample media_id as audio_media_id, and obtain Resp.speaker_id.

Query voices: Call GET /openapi/v2/video/lip_sync/tts_list. Pass speaker_type=custom to query the current user's custom voices, and identify a voice by the returned speaker_id and name.

Use a voice: When creating an Image Avatar task, pass the custom speaker_id to lip_sync_tts_speaker_id together with lip_sync_tts_content.

Delete a voice: Call DELETE /openapi/v2/video/tts_speaker/{speaker_id}. This endpoint does not have a request body.

Field flow:

Stage	Field Obtained	Used In the Next Step
Upload a voice sample	`Resp.media_id`	`audio_media_id` in the custom voice creation request
Create a custom voice	`Resp.speaker_id`	`lip_sync_tts_speaker_id` in the Image Avatar request
Query the voice list	`Resp.data[].speaker_id`	Reselect or confirm an available custom voice
Delete a custom voice	`speaker_id`	Path parameter of the DELETE endpoint

If a Custom Voice Cannot Be Used

Confirm that the custom voice creation endpoint returned ErrCode=0 and that you obtained Resp.speaker_id;

Query the voice list with speaker_type=custom and confirm that the voice belongs to the current API account;

Pass the returned speaker_id unchanged to lip_sync_tts_speaker_id, together with lip_sync_tts_content;

Do not pass the sample media_id used for voice creation to the Image Avatar TTS request.

Calling Rules Checklist

The generation request accepts only the img_id returned by the image upload endpoint, not an image file or image URL;

Both img_id and quality are required;

The finished-audio field is audio_media_id;

Finished audio and a TTS script cannot be used in the same request;

When using TTS, pass both lip_sync_tts_content and lip_sync_tts_speaker_id;

The supported resolutions are 360p, 540p, 720p, and 1080p;

The custom voice deletion endpoint does not have a request body.

Avatar

API-based Image Avatar#

Prerequisites#

Quick Start#

Step-by-Step Guide#

Step 1: Upload an Image#

Step 2: Prepare the Voice#

Step 3: Create an Image Avatar Task#

Use Uploaded Finished Audio#

Use a Built-in or Default TTS Voice#

Use a Custom TTS Voice#

Step 4: Query the Status and Get the Video#

Custom Voice Lifecycle#

If a Custom Voice Cannot Be Used#

Calling Rules Checklist#