Photo Avatar API Usage

Business Process

Description

Using the API Photo Avatar, image can be converted into video.

Image Example

Usage Example

First, obtain Topview-Uid and Authorization as request header parameters. For details, see the documentation How To Get Topview Uid And Key. Assume Topview-Uid=NsDAaOPF4jLuAie4ewyg and Authorization=Bearer sk-vEsneECh1J5eKHUw4vxHI61e7FvXPnPE1625PmSt3HB【Note: Current account is unavailable ❌】.

Step1: Execute `Avatar4 - submit task` Task

submit task

curl --location --request POST 'https://api.topview.ai/v1/photo_avatar/task/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 '{
    "templateImageFileId":"2a22d8f1364d4903a4f7ec98d2046899",
    "mode":"avatar4",
    "scriptMode":"text",
    "ttsText":"Hey, I’m Topview Avatar 4. Give me one picture, and I can make a video like this — natural, longer, and doing the moves you want.",
    "voiceId":"LaaHTrXZCVOQmB1wZUhnwmbPTAWDFtW6",
    "audioFileId":"",
    "captionId":"",
    "avatarActionPrompt":"",
    "saveCustomAiAvatar":true
}'

response

{
    "code": "200",
    "message": "Success",
    "result": {
        "taskId": "fe637b2d8e504798afb18b87a02dd4e2",
        "status": "success",
        "errorMsg": null,
        "noticeUuid": ""
    }
}

Step2: Execute `Avatar4 - query task`

query task

curl --location --request GET 'https://api.topview.ai/v1/photo_avatar/task/query?taskId=fe637b2d8e504798afb18b87a02dd4e2&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": "fe637b2d8e504798afb18b87a02dd4e2",
        "status": "success",
        "finishedVideoCoverUrl": "https://aigc.s3.amazonaws.com/api/upload/lfzUumKIt2w2oWVcUF6e/2a22d8f1364d4903a4f7ec98d2046899.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250904T034847Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250904%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=b3f3255deeb0cc6509addeee4d9be7ea2b81b0b1b3ca718478c43299888042aa",
        "finishedVideoUrl": "https://aigc.s3.amazonaws.com/analyzed_video/video/53523ee0b13a4491b9ca5f03816f7997/53523ee0b13a4491b9ca5f03816f7997_origin.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250904T034847Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250904%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=d204864945655949a207742459d8b2213dfc1294e776d89e7d7bedac45c2d795",
        "aiAvatar": {
            "aiavatarId": "9692d4ec7d47453da206ccbb5b7e44ed",
            "coverUrl": "https://aigc.s3.amazonaws.com/api/upload/lfzUumKIt2w2oWVcUF6e/2a22d8f1364d4903a4f7ec98d2046899.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250904T034847Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIARMCUIMKIOTHGVNFI%2F20250904%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=b3f3255deeb0cc6509addeee4d9be7ea2b81b0b1b3ca718478c43299888042aa"
        }
    }
}