Select Video Mask

POST

/openapi/v2/video/mask/selection

Identify candidate regions before Swap or selected-region Modify. Use exactly one source. Reuse the same source, returned keyframe_id, and selected mask_id in the next request. Preview URLs are not input IDs. An empty mask_info means no region was detected; try another frame.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Successful response.

Bodyapplication/json

🟠400

🟠401

Request Example

Shell

Minimal request (replace resource IDs)Complete scenario (replace resource IDs)

curl --location 'https://app-api.pixverse.ai/openapi/v2/video/mask/selection' \
--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
}'

Response Example

200 - Illustrative region selection

{
    "ErrCode": 0,
    "ErrMsg": "Success",
    "Resp": {
        "keyframe_id": 1,
        "keyframe_url": "https://example.com/frame.png",
        "credits": 2,
        "mask_info": [
            {
                "mask_id": "123456789",
                "mask_name": "subject",
                "mask_url": "https://example.com/mask.png"
            }
        ]
    }
}

Image Avatar

Sound Effect