The Speech (LipSync) endpoint is designed to solve voice synchronization issues in videos.
It analyzes both the audio and the speaker’s mouth movements in the video, matching them precisely. This makes your videos more expressive and engaging, adding storytelling depth.
TTS supports both built-in voices and custom voices created from user-provided sample audio.

Endpoint: https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate
API reference : https://docs.platform.pixverse.ai/speechlipsync-generation-19094278e0
Upload media reference : https://docs.platform.pixverse.ai/upload-videoaudio-19094401e0
Get TTS voices: GET https://app-api.pixverse.ai/openapi/v2/video/lip_sync/tts_list
Create a custom voice: POST https://app-api.pixverse.ai/openapi/v2/video/tts_speaker
Delete a custom voice: DELETE https://app-api.pixverse.ai/openapi/v2/video/tts_speaker/{speaker_id}

Prerequisites

Before you begin, make sure you have:

A valid PixVerse API key

A unique Ai-trace-id for each API request

An active subscription with available or purchased API credits

A Video either:

A video_id generated from PixVerse
or

An uploaded video in supported formats (mp4, mov, webm)

Max resolution: 1920

Max file size: 100MB

Max duration: 60 seconds

Audio from either:

An audio file in supported formats (.mp3, .wav, .m4a, .aac)

Max file size: 100MB

Max duration: 60 seconds
or

A script with a built-in TTS voice
or

A script with a custom TTS voice

To use a custom voice, upload a sample audio file first, then call the custom voice creation endpoint to obtain a speaker_id. Refer to the latest custom voice endpoint documentation for sample-audio limits.

Quick Start

1: Prepare Your Video

2: Prepare Your Audio or Script

3. Speech generation task

4. Check generation status & download

5. Delete a custom voice you no longer need (Optional)

Step-by-Step Guide

Step 1-1: Prepare Your Video from External video

External Video (User-Provided)

To ensure optimal results, please provide:

A .mp4, .mov, or .webm video file

Max resolution: 1920p

Max size: 100MB

Max duration: 60s

Construct your API request with the appropriate parameters:

you will get "media_id" with "video" media_type

{
    "ErrCode": 0,
    "ErrMsg": "success",
    "Resp": {
        "media_id": 0,
        "media_type": "video",
        "url": "https://media.pixverse.ai/111111.mp4"
    }
}

Step 1-2: Prepare Your Video from PixVerse API

If you previously generated a video using our API, you should already have a video_id.
To generate a Lipsync video, pass the video_id into the source_video_id field of the generation request.

Step 2 : Prepare Your Audio or Script

You can either:

Upload a pre-recorded audio file (.mp3, .wav, .m4a, or .aac, ≤ 60s, ≤ 100MB)

Use our built-in TTS service with a provided script

Upload sample audio to create a custom TTS voice, then use that voice with a script

The audio must be clear. Multiple languages and audio types are supported, including speech, singing, and advertisements.

for uploading audio file
Construct your API request with the appropriate parameters:

you will get "media_id" with "audio" media_type

{
    "ErrCode": 0,
    "ErrMsg": "success",
    "Resp": {
        "media_id": 0,
        "media_type": "audio",
        "url": "https://media.pixverse.ai/111111.mp3"
    }
}

for TTS service

You can get both built-in voices and the current user's custom voices from the API. This endpoint uses query parameters and does not require a request body.

Parameter Name	Required	Type	Description
page_num	optional	int	Page number
page_size	optional	int	Number of items per page
speaker_type	optional	string	`system`: built-in voices; `custom`: custom voices; `all`: all voices. Default: `all`

Built-in voices and custom voices use the same base fields in the returned list: speaker_id and name. Pass the selected speaker_id to lip_sync_tts_speaker_id in the generation request.

Create a custom TTS voice

Upload a sample audio file through the media upload endpoint and obtain Resp.media_id.

Pass that media_id as audio_media_id to the custom voice creation endpoint:

Parameter Name	Required	Type	Description
name	required	string	Custom voice name
audio_media_id	required	int	Sample audio `media_id` returned by the upload API

Responses

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "speaker_id": "your-custom-speaker-id"
  }
}

In the custom voice creation endpoint, audio_media_id identifies the sample audio used for voice cloning. In the Lipsync generation endpoint, audio_media_id identifies the finished audio used for lip synchronization. The field name is the same, but its purpose depends on the endpoint.

Step 3: Send Speech(Lip Sync) API Request

4 cases for generation task

Custom voices and built-in voices use the same TTS request structure, so custom voices do not add another field combination.

source_video_id + audio_media_id

{
"source_video_id": 123456,
"audio_media_id": 234567
}

source_video_id + lip_sync_tts_speaker_id + lip_sync_tts_content

{
"source_video_id": 123456,
"lip_sync_tts_speaker_id": "auto-or-custom-speaker-id",
"lip_sync_tts_content": "hello this is harry, where are you from?"
}

video_media_id + audio_media_id

{
"video_media_id": 123456,
"audio_media_id": 234567
}

video_media_id + lip_sync_tts_speaker_id + lip_sync_tts_content

{
"video_media_id": 123456,
"lip_sync_tts_speaker_id": "auto-or-custom-speaker-id",
"lip_sync_tts_content": "hello this is harry, where are you from?"
}

https://docs.platform.pixverse.ai/speechlipsync-generation-19094278e0

Step 4 Handle the API Response

The API returns a JSON response with a video_id:

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": 0,
    "credits": 0
  }
}

Step 5 Check Generation Status

After creating the task, you will receive a video_id

Query periodically Get Video Generation Status API using this video_id

The status will change from 5 to 1 when processing is complete

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 5,
   "style": "string",
   "url": "string"
 }
}

Step 6 Download the Generated Video

You can access a generated video with "url"

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 1,
   "style": "string",
   "url": "string"
 }
}

Step 7 (Optional): Delete a custom voice

When you no longer need a custom voice, place the speaker_id returned by the custom voice creation endpoint in the request path:

Parameter Name	Required	Type	Description
speaker_id	required	string	Custom voice ID returned by the custom voice creation endpoint; pass it as a path parameter

Responses

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "speaker_id": "your-custom-speaker-id",
    "deleted": true
  }
}

Troubleshooting

Common issue

Your video is stuck in "Generating" status and hasn't completed after a long wait.

Please check if you're using the same AI-trace-ID for every request. This is the most common cause of this issue.

Status codes: 1: Generation successful; 5: Waiting for generation; 7: Content moderation failure; 8: Generation failed;

If you encounter status code 7, it means your generated video was filtered by our content moderation system. Please modify your parameters and try again. Any credits used for filtered videos will be automatically refunded to your account.

A custom voice cannot be used.

Confirm that the custom voice creation endpoint returned a speaker_id, and pass that exact value to lip_sync_tts_speaker_id.

Confirm that the custom voice belongs to the current API account. If creation fails, troubleshoot using the returned ErrCode and ErrMsg; this guide does not assume unpublished custom error codes.

Common error codes

400/500 status : Incorrect code

400013 : Invalid binding request: incorrect parameter type or value

400017 : Invalid parameter

Either "audio_media_id" or "lip_sync_tts_speaker_id" + "lip_sync_tts_content" must be provided

couldn’t find a matching source_video_id. Please re-upload your video and try again.

couldn’t find a matching video_media_id. Please re-upload your video and try again.

Invalid media_type: not a video resource. Please check the ID and try again.

couldn’t find a matching audio_media_id. Please re-upload your audio and try again.

Invalid media_type: not an audio resource. Please check the ID and try again.

The specified speaker ID is invalid or not supported.

TTS text must be within 200 characters.

TTS content is invalid or does not meet content guidelines

500044 : Reached the limit for concurrent generations.

Speech parameter

If you want to use this feature via parameters, please refer to the following details:

Supported APIs: Text-to-Video / Image-to-Video / Keyframe-to-Video

Supported Parameters:

parameter	type	required	description
lip_sync_tts_switch	boolean	optional	true, false Set to true if you want to enable this feature. Default is false.
lip_sync_tts_content	string	optional	TTS script content; refer to the corresponding video generation API for the length limit.
lip_sync_tts_speaker_id	string	optional	ID from Get Speech TTS list; you can use a built-in voice ID or the `speaker_id` returned by the custom voice creation endpoint.

Credits Billing:

Regardless of the input content, enabling lip_sync_switch will be billed based on the generated video length.

Formula: video_duration × 4 credits (4credits from speech biiling )

Speech(Lip sync)

Prerequisites#

Quick Start#

Step-by-Step Guide#

Step 1-1: Prepare Your Video from External video#

Step 1-2: Prepare Your Video from PixVerse API#

Step 2 : Prepare Your Audio or Script#

Step 3: Send Speech(Lip Sync) API Request#

source_video_id + audio_media_id#

source_video_id + lip_sync_tts_speaker_id + lip_sync_tts_content#

video_media_id + audio_media_id#

video_media_id + lip_sync_tts_speaker_id + lip_sync_tts_content#

Step 4 Handle the API Response#

Step 5 Check Generation Status#

Step 6 Download the Generated Video#

Step 7 (Optional): Delete a custom voice#

Troubleshooting#

Common issue#

Common error codes#

Speech parameter#