How to use Modify?

Overview

The Modify feature allows you to edit any part of an existing video — including adding, replacing, removing, modifying elements, or transforming the overall style.

It enables fast video remixing and secondary creation, turning one video into many new creative possibilities.

Core features

Swap : Replace people or subjects in the video

Add : Add new elements (e.g. accessories, props, characters) into the video

Edit : Modify the video with a free-form prompt

Restyle : Transform the entire video into a different visual style

No.	Core Feature	Sub-Feature	Description	Detailed Capability
1	Swap	Single Subject Swap	Replace one person or subject in the video	• Single mode: 1 selection area, 1 reference image
2	Swap	Multi-Subject Swap	Replace 2–3 people or subjects in the video at the same time	• Multi mode: up to 3 selection areas, up to 3 images for each subject
3	Add	Smart Add	Add new elements (e.g. accessories, props, characters) into the video	• Supports 1 selection area(optional) and 1 reference image(optional)
4	Edit	Remove	Remove elements from the video	• Remove: intelligently fills the background after removal.
5	Edit	Type Anything	Modify the video with a free-form prompt	• Supports changing lighting, season, weather, and other scene attributes
6	Edit	Text Replacement	Detect and replace embedded text in the video	• Modify in-video text directly with a prompt
7	Restyle	Scene Style Transfer	Transform the entire video into a different visual style	• Supports 3D, 2D, comic, ink painting, and other styles

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_id

generated from PixVerse
or

from external uploaded

An uploaded video in supported formats (mp4, mov)

Max resolution: 1920

Max file size: 100MB

Max duration: 30 seconds

The img_id of the image you want to use in Modify

The mask_id from swap_mask endpoint or mask_url form own your side

keyframe_id when you use swap feature in Modify

Requirements & Validation Rules

When using specific features, please note that if a mask is used in the prompt, it should be referenced as @selection0. For multiple masks, use @selection1, @selection2. If reference images are uploaded, use @img0, @img1, etc.

Please ensure that the number of masks and images matches the references used in the prompt. If they do not match, or if the prompt does not explicitly reference them, the result may not match your expectations.

If you do not already have mask data, you can use the Swap Mask API. In this case, the video_id used to generate the mask must correspond to the mask_id used in the generation request.

If you already have your own mask image, you can provide it using the mask_url parameter.

keyframe_id specifies which frame of the video is used for editing. Therefore, the frame used when creating the mask must match the keyframe_id in the request.

Quick Start

1: Prepare Your Videos

2. Prepare Your Image

3. Prepare your mask

4. Modify generation API task

5. Check generation status & download

Step-by-Step Guide

You can input your video in two ways:

Step 1-1: Prepare Your Video from External video

External Video (User-Provided)

To ensure optimal results, please provide:

A .mp4 or .mov video file

Max resolution: 1920p

Max size: 100MB

Max duration: 30s

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 extend this video, pass the video_id into the source_video_id field of the generation request.

Step 1-3. Prepare Your Image

Use high-quality and clear images. Higher resolution is recommended for better results.

Step 1-4. Prepare Your Mask

Use high-quality and clear images. Higher resolution is recommended for better results.

Step 2: Send Modify API Request

if a video is from pixverse API please use "source_video_id":111 instead of "video_media_id"

Request

🔧 Parameter Details

Parameter Name	Type	Required	Description	Example / Allowed Values	Notes
`source_video_id`	int	One of `source_video_id` or `video_media_id` is required	Video generated from PixVerse	12345	Cannot be used together with `video_media_id`
`video_media_id`	int	One of `source_video_id` or `video_media_id` is required	Externally uploaded video	12345	Cannot be used together with `source_video_id`
`prompt`	string	Yes	The prompt describing the modification you want to make.		When using specific features, please note that if a mask is used in the prompt, it should be referenced as @selection0. For multiple masks, use @selection1, @selection2. If reference images are uploaded, use @img0, @img1, etc.
`img_ids`	array[int]	No	Uploaded image IDs used in the prompt	`[123, 456]`	At least 1 item if provided
`mask_ids`	array[string]	Optional, choose one of `mask_ids` or `mask_urls`	Mask IDs generated by the mask API	`["3847593904"]`	At least 1 item if provided
`mask_urls`	array[string]	Optional, choose one of `mask_ids` or `mask_urls`	Publicly accessible mask image URLs	`["https://example.com/mask.png"]`	At least 1 item if provided
`keyframe_id`	int	No	Specifies which frame of the video is used for swap features in modify	`1`	Only one value can be provided. Does not need to match the number of `mask_ids`.
`quality`	string	Yes	Output video resolution	`"360p"`, `"540p"`, `"720p"`	`"1080p"` is not supported
`seed`	int	No	Random seed used for reproducible results	`0 ~ 2147483647`	Optional

Feature Details


{   "video_media_id": 1234,   "prompt": "@selection0 subject is swapped with @img0",   "img_ids": [123, 123],   "mask_ids": ["3847593904"],   "keyframe_ids": 1,   "quality": "540p" }
{ "video_media_id":1234,"prompt":"@selection0 subject is swapped with @img0 @selection1 subject is swapped with @img1 @selection2 subject is swapped with @img2","img_ids":[123,123,123], "mask_ids":["3847593904","3847593904","3847593904"], "keyframe_ids":1, "quality":"540p"  } 
{ "video_media_id":1234, "prompt":"add @img0, @img1", "img_ids":[123,123], "quality":"540p"} 
{ "video_media_id":1234, "prompt":"remove xxx", "mask_ids":["3847593904"], "quality":"540p" } 
{ "video_media_id":1234, "prompt":"把天气变成冬天白天", "quality":"540p" }  
 { "video_media_id":1234, "prompt":"change the text to "Happy birthday", "quality":"540p" }  
{ "video_media_id":1234, "prompt":"The video is restyled with @ima0", "img_ids":[123], "quality":"540p" } 

No.	Core Feature	Sub-Feature	Description	Detailed Capability	Code Example
1	Swap	Single Subject Swap	Replace one person or subject in the video	• Single mode: 1 selection area, 1 reference image	`{ "video_media_id": 1234, "prompt": "@selection0 subject is swapped with @img0", "img_ids": [123, 123], "mask_ids": ["3847593904"], "keyframe_ids": 1, "quality": "540p" }`
2	Swap	Multi-Subject Swap	Replace 2–3 people or subjects in the video at the same time	• Multi mode: up to 3 selection areas, supports custom images for each subject	`{ "video_media_id":1234,"prompt":"@selection0 subject is swapped with @img0 @selection1 subject is swapped with @img1 @selection2 subject is swapped with @img2","img_ids":[123,123,123], "mask_ids":["3847593904","3847593904","3847593904"], "keyframe_ids":1, "quality":"540p" }`
3	Add	Smart Add	Add new elements (e.g. accessories, props, characters) into the video	• Supports 1 selection area and 1 reference image	`{ "video_media_id":1234, "prompt":"add @img0, @img1", "img_ids":[123,123], "quality":"540p"}`
4	Edit	Remove	Remove elements from the video	• Remove: intelligently fills the background after removal	`{ "video_media_id":1234, "prompt":"remove xxx", "mask_ids":["3847593904"], "quality":"540p" }`
5	Edit	Type Anything	Modify the video with a free-form prompt	• Supports changing lighting, season, weather, and other scene attributes	`{ "video_media_id":1234, "prompt":"把天气变成冬天白天", "quality":"540p" }`
6	Edit	Text Replacement	Detect and replace embedded text in the video	• Modify in-video text directly with a prompt	`{ "video_media_id":1234, "prompt":"change the text to "Happy birthday", "quality":"540p" }`
7	Restyle	Scene Style Transfer	Transform the entire video into a different visual style	• Supports 3D, 2D, comic, ink painting, and other styles	`{ "video_media_id":1234, "prompt":"The video is restyled with @ima0", "img_ids":[123], "quality":"540p" }`

Step 3. Handle the API Response

The API returns a JSON response with a video_id:

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": 0,
    "credit":10
  }
}

Step 4. 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 5. 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"
 }
}

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.

Common error codes

400/500 status : Incorrect code

400013 : Invalid binding request: incorrect parameter type or value

400017 : Invalid parameter

500044 : Reached the limit for concurrent generations.

Credits

Model	Billing rule	360p	540p	720p	1080p
-	credits per 1s	8	10	12	-

Overview#

Core features#

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 1-3. Prepare Your Image#

Step 1-4. Prepare Your Mask#

Step 2: Send Modify API Request#

Step 3. Handle the API Response#

Step 4. Check Generation Status#

Step 5. Download the Generated Video#

Troubleshooting#

Common issue#

Common error codes#

Credits#