Subject Replacement (Swap)

POST

/openapi/v2/video/swap/generate

Call Select Video Mask first. The video source, keyframe_id, and mask_id must come from the same Mask workflow. Use img_id for the replacement image, not img_ids. Source video: up to 30 seconds and 100 MB, longest side up to 1920 px. 1080p is not supported.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Successful response.

Bodyapplication/json

🟠400

🟠401

Request Example

Shell

curl --location 'https://app-api.pixverse.ai/openapi/v2/video/swap/generate' \
--header 'API-KEY: your-api-key' \
--header 'Ai-trace-id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
    "source_video_id": 123456794,
    "keyframe_id": 1,
    "mask_id": "123456797",
    "img_id": 123456791,
    "quality": "540p"
}'

Response Example

200 - Illustrative accepted task; poll to completion

{
    "ErrCode": 0,
    "ErrMsg": "Success",
    "Resp": {
        "video_id": 123456789,
        "credits": 10
    }
}

Sound Effect

Motion Control (Mimic)