Getting Started

Business Process

Description

productImageFileId ==> bgRemovedImageFileId(productImageWithoutBackgroundFileId)

(avatarId or templateImageFileId) + productImageWithoutBackgroundFileId ==> imageId & url

imageId ==> finishedVideoUrl

Image Example

Usage Example

Assume Topview-Uid=NsDAaOPF4jLuAie4ewyg,Authorization=Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB【Note: Current account not available❌】

Step1：Generate Product Image Without Background

submit task

curl --location --request POST 'https://api.topview.ai/v1/common_task/remove_background/submit' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive' \
--data-raw '{
    "productImageFileId":"dff804f385b84d4fb9c1b51c70f3755f"
}'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "4274b375c30844c8bd0b1e4b6e44fb5f",
        "status": "success",
        "errorMsg": null
    }
}

query task

curl --location --request GET 'https://api.topview.ai/v1/common_task/remove_background/query?taskId=4274b375c30844c8bd0b1e4b6e44fb5f&needCloudFrontUrl=' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "4274b375c30844c8bd0b1e4b6e44fb5f",
        "status": "success",
        "bgRemovedImageFileId": "670c78f3dca2413f8546e29085c07224",
        "bgRemovedImagePath": "https://aigc.s3.amazonaws.com/analyzed_video/task/background_removed/a9fb0860ad944371a6a62a24152b9ec5/cropped_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250812T070536Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250812%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=76559973bd10f59cb969c32b9ea4da2e1b596f2ac11f8c05e74db806eb086bd9",
        "bgRemovedImageWidth": 528,
        "bgRemovedImageHeight": 720,
        "maskImageFileId": "3d4b09ad5b4646cb8d28f9d7f0ebb50f",
        "maskImagePath": "https://aigc.s3.amazonaws.com/analyzed_video/task/background_removed/a9fb0860ad944371a6a62a24152b9ec5/mask.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250812T070536Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250812%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=523acc3718daccea57f7e2ce546e09dd8259a13af7ab248cd6fab9d21967d6b6",
        "maskImageWidth": 720,
        "maskImageHeight": 720
    }
}

Step2：Execute `Replace Product Image` Task

manual mode

submit task
- Note: Use the bgRemovedImageFileId field from Step 1 - Query Task

curl --location --request POST 'https://api.topview.ai/v2/product_avatar/task/image_replace/submit' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive' \
--data-raw '{
    "generateImageMode": "manual",
    "templateImageFileId": "c62216b7e35e4e8598edc29a4041c7b6",
    "productImageWithoutBackgroundFileId": "722e4c0ebdc148e295df9fe30c3160bd",
    "userFaceImageFileId": "",
    "imageEditPrompt": "",
    "location": [
        [
            0.31470588235294117,
            0.6390728476821192
        ],
        [
            0.7489529411764706,
            0.6390728476821192
        ],
        [
            0.7489529411764706,
            0.9724056291390728
        ],
        [
            0.31470588235294117,
            0.9724056291390728
        ]
    ]
}'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "3179dd887d294ab797fa85eea49fb25f",
        "status": "success",
        "errorMsg": null
    }
}

query task

curl --location --request GET 'https://api.topview.ai/v2/product_avatar/task/image_replace/query?taskId=3179dd887d294ab797fa85eea49fb25f&needCloudFrontUrl' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "3179dd887d294ab797fa85eea49fb25f",
        "status": "success",
        "replaceProductResult": [
            {
                "imageId": "bd39ae55d7634d2f8a4dd5c688ebb800",
                "faceExistence": true,
                "url": "https://aigc.s3.amazonaws.com/analyzed_video/task/object_replace_llm/a42d3557743f445c919b56963dc2e88f/a42d3557743f445c919b56963dc2e88f_234.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250813T114806Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250813%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=68e1b9dfadcfdc9cebde50145423ba82193b910fd0f3a01d920141a1e3b83a28"
            },
            {
                "imageId": "1ed9fef518104317baab5645243445eb",
                "faceExistence": false,
                "url": "https://aigc.s3.amazonaws.com/analyzed_video/task/object_replace_llm/9ef6c0a06d9f4f33b409495b91564448/9ef6c0a06d9f4f33b409495b91564448_234.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250813T114806Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250813%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=a8976bd40aaf503f46e7e171b9d883a4504db90057d0964bb6071ef2a784f982"
            }
        ]
    }
}

auto mode

submit task
- Note: Use the bgRemovedImageFileId field from Step 1 - Query Task

curl --location --request POST 'https://api.topview.ai/v2/product_avatar/task/image_replace/submit' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive' \
--data-raw '{
    "generateImageMode": "auto",
    "templateImageFileId":"c62216b7e35e4e8598edc29a4041c7b6",
    "productImageWithoutBackgroundFileId": "722e4c0ebdc148e295df9fe30c3160bd",
    "userFaceImageFileId": "",
    "imageEditPrompt":"Replace the item in the hand of the person in Picture 1 with the one in Picture 2. Keep the composition position and gesture of the person in Picture 1 unchanged, and ensure that the features, appearance and details of the item in Picture 2 remain exactly the same after the change."
}'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "53030cca5d8a4119848373746615fa0e",
        "status": "success",
        "errorMsg": null
    }
}

query task

curl --location --request GET 'https://api.topview.ai/v2/product_avatar/task/image_replace/query?taskId=53030cca5d8a4119848373746615fa0e&needCloudFrontUrl' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "53030cca5d8a4119848373746615fa0e",
        "status": "success",
        "replaceProductResult": [
            {
                "imageId": "3e8936361cd8444fbcceb6c247eebc58",
                "faceExistence": true,
                "url": "https://aigc.s3.amazonaws.com/analyzed_video/task/object_replace_llm/778bff25cef7489b984bc0f90ddd3335/778bff25cef7489b984bc0f90ddd3335_54.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250813T120527Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250813%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=88f2c576ee849d7b8e6e2bdb46b50cdec27a8d94a35bf8228d6feaa2df8154c3"
            }
        ]
    }
}

Step3：Execute `Image2Video` Task

submit task
- Note: Use the imageId field from Step 2 - Query Task

curl --location --request POST 'https://api.topview.ai/v2/product_avatar/task/image2Video/submit' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive' \
--data-raw '{
    "replaceProductTaskImageId": "7e66ece3b4384e929fff91da2918e2d6",
    "mode": "pro",
    "scriptMode": "text",
    "ttsText": "test product avatar",
    "voiceId": "zeeTdrCqbhpVKOucLtOKdhytM7rbJx5t",
    "audioFileId": "",
    "captionId": "3cfcb29df99746d4b438e169dda47647"
}'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "8aa992b4cfd24082a564710cbee2132c",
        "status": "success",
        "errorMsg": null
    }
}

query task

curl --location --request GET 'https://api.topview.ai/v2/product_avatar/task/image2Video/query?taskId=8aa992b4cfd24082a564710cbee2132c&needCloudFrontUrl' \
--header 'Topview-Uid: NsDAaOPF4jLuAie4ewyg' \
--header 'Authorization: Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB' \
--header 'Accept: */*' \
--header 'Host: api.topview.ai' \
--header 'Connection: keep-alive'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "8aa992b4cfd24082a564710cbee2132c",
        "status": "success",
        "finishedVideoUrl": "https://aigc.s3.amazonaws.com/analyzed_video/task/export/c708644f5ece452d8a539fe5da910af9_topview.ai.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250812T071822Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250812%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=6053eab8401d5251bf38ae050d308316827c76c46bb3e969ca99e800e777f662",
        "aiAvatar": {
            "aiavatarId": "2c3f371464924c59a19d4ae7d56b58fa",
            "aiavatarName": "Product Avatar_250812071343_1",
            "gender": null,
            "coverUrl": "https://aigc.s3.amazonaws.com/analyzed_video/task/custom_aiavatar/lfzUumKIt2w2oWVcUF6e/product_avatar/f283edddf9bd4618a9eb4681e215ab8e.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250812T071822Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250812%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=0683886dce088a6a665a5742fbe8d063ffeeee23383cca7a7faf86d6afa872b6",
            "previewVideoUrl": "https://aigc.s3.amazonaws.com/aiavatar/user_instant_model/lfzUumKIt2w2oWVcUF6e/d76f909997cd48899a198be1fd83bad6/result/3db5e6b280314e34ad79f4a9d2f0b4a4.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250812T071822Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250812%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=e8b7af8aca2e75630e6ebd51d196b3c46a97bd9949976ceae6cab39583e0b25d",
            "ethnicities": null,
            "voiceoverIdDefault": "zeeTdrCqbhpVKOucLtOKdhytM7rbJx5t",
            "faceSquareConfig": null
        }
    }
}

Business Process

Usage Example

Step1：Generate Product Image Without Background

Step2：Execute Replace Product Image Task

Step3：Execute Image2Video Task

Step2：Execute `Replace Product Image` Task

Step3：Execute `Image2Video` Task