[{"data":1,"prerenderedAt":1002},["ShallowReactive",2],{"guide-\u002Fguides-zh\u002Favatars":3,"developer-code-71rrns":995,"developer-code-1r19c2f":996,"developer-code-1dpm3n2":997,"developer-code-1mezl69":998,"developer-code-1oilrhu":999,"developer-code-nntzbn":1000,"developer-code-10t76cq":1001},{"id":4,"title":5,"body":6,"description":986,"extension":987,"meta":988,"navigation":989,"path":991,"seo":992,"stem":993,"__hash__":994},"guidesZh\u002Fguides-zh\u002Favatars.md","数字人形象 API",{"type":7,"value":8,"toc":977},"minimark",[9,13,18,100,104,115,154,422,460,474,478,488,521,526,700,706,713,717,723,760,786,820,824,829,897,905,909,912,939,943,973],[10,11,12],"p",{},"VisionStory 数字人形象 API 为数字人视频提供出镜角色。你可以查询自己的形象或公共形象库，通过一张肖像创建可复用的专属形象，并控制专属形象在各个支持画幅中的取景。",[14,15,17],"h2",{"id":16},"ai-avatar-api-endpoints","数字人形象接口",[19,20,21,37],"table",{},[22,23,24],"thead",{},[25,26,27,31,34],"tr",{},[28,29,30],"th",{},"方法",[28,32,33],{},"路径",[28,35,36],{},"功能",[38,39,40,57,72,86],"tbody",{},[25,41,42,49,54],{},[43,44,45],"td",{},[46,47,48],"code",{},"GET",[43,50,51],{},[46,52,53],{},"\u002Fapi\u002Fv1\u002Favatars",[43,55,56],{},"分页查询专属形象或公共形象库",[25,58,59,64,69],{},[43,60,61],{},[46,62,63],{},"POST",[43,65,66],{},[46,67,68],{},"\u002Fapi\u002Fv1\u002Favatar",[43,70,71],{},"通过图片创建专属形象",[25,73,74,78,83],{},[43,75,76],{},[46,77,63],{},[43,79,80],{},[46,81,82],{},"\u002Fapi\u002Fv1\u002Favatar\u002Fframing",[43,84,85],{},"更新专属形象在一个画幅下的取景",[25,87,88,93,97],{},[43,89,90],{},[46,91,92],{},"DELETE",[43,94,95],{},[46,96,68],{},[43,98,99],{},"删除你的一个专属形象",[14,101,103],{"id":102},"list-owned-or-public-avatars","查询专属形象或公共形象",[10,105,106,107,110,111,114],{},"每次请求只返回一种形象。",[46,108,109],{},"GET \u002Fapi\u002Fv1\u002Favatars"," 默认查询当前账户拥有的形象；设置 ",[46,112,113],{},"is_public=true"," 后改为查询公共形象库。结果按创建时间从新到旧排列，并使用 cursor 分页：",[116,117,122],"pre",{"className":118,"code":119,"language":120,"meta":121,"style":121},"language-bash shiki shiki-themes github-light github-dark","curl -s -H \"X-API-Key: $VISIONSTORY_API_KEY\" \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars?is_public=false&limit=20\"\n","bash","",[46,123,124],{"__ignoreMap":121},[125,126,129,133,137,140,144,148,151],"span",{"class":127,"line":128},"line",1,[125,130,132],{"class":131},"sScJk","curl",[125,134,136],{"class":135},"sj4cs"," -s",[125,138,139],{"class":135}," -H",[125,141,143],{"class":142},"sZZnC"," \"X-API-Key: ",[125,145,147],{"class":146},"sVt8B","$VISIONSTORY_API_KEY",[125,149,150],{"class":142},"\"",[125,152,153],{"class":142}," \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars?is_public=false&limit=20\"\n",[116,155,159],{"className":156,"code":157,"language":158,"meta":121,"style":121},"language-python shiki shiki-themes github-light github-dark","import os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\nparams = {\"is_public\": False, \"limit\": 20}\n\nwhile True:\n    response = requests.get(\n        \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars\",\n        headers=headers,\n        params=params,\n        timeout=10,\n    )\n    data = response.json()[\"data\"]\n    for avatar in data[\"avatars\"]:\n        print(avatar[\"avatar_id\"], avatar[\"default_voice_id\"])\n    if not data[\"next_cursor\"]:\n        break\n    params[\"cursor\"] = data[\"next_cursor\"]\n","python",[46,160,161,170,178,185,209,242,247,259,270,279,291,302,315,321,338,359,380,396,402],{"__ignoreMap":121},[125,162,163,167],{"class":127,"line":128},[125,164,166],{"class":165},"szBVR","import",[125,168,169],{"class":146}," os\n",[125,171,173,175],{"class":127,"line":172},2,[125,174,166],{"class":165},[125,176,177],{"class":146}," requests\n",[125,179,181],{"class":127,"line":180},3,[125,182,184],{"emptyLinePlaceholder":183},true,"\n",[125,186,188,191,194,197,200,203,206],{"class":127,"line":187},4,[125,189,190],{"class":146},"headers ",[125,192,193],{"class":165},"=",[125,195,196],{"class":146}," {",[125,198,199],{"class":142},"\"X-API-Key\"",[125,201,202],{"class":146},": os.environ[",[125,204,205],{"class":142},"\"VISIONSTORY_API_KEY\"",[125,207,208],{"class":146},"]}\n",[125,210,212,215,217,219,222,225,228,231,234,236,239],{"class":127,"line":211},5,[125,213,214],{"class":146},"params ",[125,216,193],{"class":165},[125,218,196],{"class":146},[125,220,221],{"class":142},"\"is_public\"",[125,223,224],{"class":146},": ",[125,226,227],{"class":135},"False",[125,229,230],{"class":146},", ",[125,232,233],{"class":142},"\"limit\"",[125,235,224],{"class":146},[125,237,238],{"class":135},"20",[125,240,241],{"class":146},"}\n",[125,243,245],{"class":127,"line":244},6,[125,246,184],{"emptyLinePlaceholder":183},[125,248,250,253,256],{"class":127,"line":249},7,[125,251,252],{"class":165},"while",[125,254,255],{"class":135}," True",[125,257,258],{"class":146},":\n",[125,260,262,265,267],{"class":127,"line":261},8,[125,263,264],{"class":146},"    response ",[125,266,193],{"class":165},[125,268,269],{"class":146}," requests.get(\n",[125,271,273,276],{"class":127,"line":272},9,[125,274,275],{"class":142},"        \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars\"",[125,277,278],{"class":146},",\n",[125,280,282,286,288],{"class":127,"line":281},10,[125,283,285],{"class":284},"s4XuR","        headers",[125,287,193],{"class":165},[125,289,290],{"class":146},"headers,\n",[125,292,294,297,299],{"class":127,"line":293},11,[125,295,296],{"class":284},"        params",[125,298,193],{"class":165},[125,300,301],{"class":146},"params,\n",[125,303,305,308,310,313],{"class":127,"line":304},12,[125,306,307],{"class":284},"        timeout",[125,309,193],{"class":165},[125,311,312],{"class":135},"10",[125,314,278],{"class":146},[125,316,318],{"class":127,"line":317},13,[125,319,320],{"class":146},"    )\n",[125,322,324,327,329,332,335],{"class":127,"line":323},14,[125,325,326],{"class":146},"    data ",[125,328,193],{"class":165},[125,330,331],{"class":146}," response.json()[",[125,333,334],{"class":142},"\"data\"",[125,336,337],{"class":146},"]\n",[125,339,341,344,347,350,353,356],{"class":127,"line":340},15,[125,342,343],{"class":165},"    for",[125,345,346],{"class":146}," avatar ",[125,348,349],{"class":165},"in",[125,351,352],{"class":146}," data[",[125,354,355],{"class":142},"\"avatars\"",[125,357,358],{"class":146},"]:\n",[125,360,362,365,368,371,374,377],{"class":127,"line":361},16,[125,363,364],{"class":135},"        print",[125,366,367],{"class":146},"(avatar[",[125,369,370],{"class":142},"\"avatar_id\"",[125,372,373],{"class":146},"], avatar[",[125,375,376],{"class":142},"\"default_voice_id\"",[125,378,379],{"class":146},"])\n",[125,381,383,386,389,391,394],{"class":127,"line":382},17,[125,384,385],{"class":165},"    if",[125,387,388],{"class":165}," not",[125,390,352],{"class":146},[125,392,393],{"class":142},"\"next_cursor\"",[125,395,358],{"class":146},[125,397,399],{"class":127,"line":398},18,[125,400,401],{"class":165},"        break\n",[125,403,405,408,411,414,416,418,420],{"class":127,"line":404},19,[125,406,407],{"class":146},"    params[",[125,409,410],{"class":142},"\"cursor\"",[125,412,413],{"class":146},"] ",[125,415,193],{"class":165},[125,417,352],{"class":146},[125,419,393],{"class":142},[125,421,337],{"class":146},[10,423,424,425,428,429,432,433,436,437,440,441,444,445,444,448,451,452,455,456,459],{},"响应结构为 ",[46,426,427],{},"{ \"avatars\": [...], \"next_cursor\": 0 }","；",[46,430,431],{},"next_cursor=0"," 表示没有下一页。",[46,434,435],{},"limit"," 可取 1–100，默认值为 20。专属形象会返回真实的 ",[46,438,439],{},"created_at","，以及按 ",[46,442,443],{},"9:16","、",[46,446,447],{},"16:9",[46,449,450],{},"1:1"," 顺序排列的三项 ",[46,453,454],{},"framing","；公共形象始终返回 ",[46,457,458],{},"framing: null","。",[10,461,462,463,466,467,470,471,459],{},"始终从该接口返回的结果中选择 ",[46,464,465],{},"avatar_id","，不要在代码中写死。要使用形象已配置的声音，请将非空的 ",[46,468,469],{},"default_voice_id"," 复制到 ",[46,472,473],{},"text_script.voice_id",[14,475,477],{"id":476},"create-an-ai-avatar-from-a-photo","通过照片创建数字人形象",[10,479,480,481,483,484,487],{},"提交一张肖像图片，即可获得 ",[46,482,465],{},"。图片来源必须二选一：可公开访问的 HTTPS URL，或包含 Base64 数据的 ",[46,485,486],{},"inline_data","：",[116,489,491],{"className":118,"code":490,"language":120,"meta":121,"style":121},"curl -s -H \"X-API-Key: $VISIONSTORY_API_KEY\" -H \"Content-Type: application\u002Fjson\" -d '{\"img_url\": \"https:\u002F\u002Fyour.site\u002Fportrait.jpg\"}' https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\n",[46,492,493],{"__ignoreMap":121},[125,494,495,497,499,501,503,505,507,509,512,515,518],{"class":127,"line":128},[125,496,132],{"class":131},[125,498,136],{"class":135},[125,500,139],{"class":135},[125,502,143],{"class":142},[125,504,147],{"class":146},[125,506,150],{"class":142},[125,508,139],{"class":135},[125,510,511],{"class":142}," \"Content-Type: application\u002Fjson\"",[125,513,514],{"class":135}," -d",[125,516,517],{"class":142}," '{\"img_url\": \"https:\u002F\u002Fyour.site\u002Fportrait.jpg\"}'",[125,519,520],{"class":142}," https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\n",[10,522,523,524,487],{},"使用本地文件时，先将其编码为 Base64，再放入 ",[46,525,486],{},[116,527,529],{"className":156,"code":528,"language":158,"meta":121,"style":121},"import base64\nimport os\nimport requests\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\nwith open(\"\u002Fpath\u002Fto\u002Fimage.jpg\", \"rb\") as f:\n    encoded = base64.b64encode(f.read()).decode(\"utf-8\")\n\npayload = {\"inline_data\": {\"mime_type\": \"image\u002Fjpg\", \"data\": encoded}}\nresponse = requests.post(\"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\", json=payload, headers=headers)\nprint(response.json()[\"data\"][\"avatar_id\"])\n",[46,530,531,538,544,550,554,570,574,602,618,622,652,683],{"__ignoreMap":121},[125,532,533,535],{"class":127,"line":128},[125,534,166],{"class":165},[125,536,537],{"class":146}," base64\n",[125,539,540,542],{"class":127,"line":172},[125,541,166],{"class":165},[125,543,169],{"class":146},[125,545,546,548],{"class":127,"line":180},[125,547,166],{"class":165},[125,549,177],{"class":146},[125,551,552],{"class":127,"line":187},[125,553,184],{"emptyLinePlaceholder":183},[125,555,556,558,560,562,564,566,568],{"class":127,"line":211},[125,557,190],{"class":146},[125,559,193],{"class":165},[125,561,196],{"class":146},[125,563,199],{"class":142},[125,565,202],{"class":146},[125,567,205],{"class":142},[125,569,208],{"class":146},[125,571,572],{"class":127,"line":244},[125,573,184],{"emptyLinePlaceholder":183},[125,575,576,579,582,585,588,590,593,596,599],{"class":127,"line":249},[125,577,578],{"class":165},"with",[125,580,581],{"class":135}," open",[125,583,584],{"class":146},"(",[125,586,587],{"class":142},"\"\u002Fpath\u002Fto\u002Fimage.jpg\"",[125,589,230],{"class":146},[125,591,592],{"class":142},"\"rb\"",[125,594,595],{"class":146},") ",[125,597,598],{"class":165},"as",[125,600,601],{"class":146}," f:\n",[125,603,604,607,609,612,615],{"class":127,"line":261},[125,605,606],{"class":146},"    encoded ",[125,608,193],{"class":165},[125,610,611],{"class":146}," base64.b64encode(f.read()).decode(",[125,613,614],{"class":142},"\"utf-8\"",[125,616,617],{"class":146},")\n",[125,619,620],{"class":127,"line":272},[125,621,184],{"emptyLinePlaceholder":183},[125,623,624,627,629,631,634,637,640,642,645,647,649],{"class":127,"line":281},[125,625,626],{"class":146},"payload ",[125,628,193],{"class":165},[125,630,196],{"class":146},[125,632,633],{"class":142},"\"inline_data\"",[125,635,636],{"class":146},": {",[125,638,639],{"class":142},"\"mime_type\"",[125,641,224],{"class":146},[125,643,644],{"class":142},"\"image\u002Fjpg\"",[125,646,230],{"class":146},[125,648,334],{"class":142},[125,650,651],{"class":146},": encoded}}\n",[125,653,654,657,659,662,665,667,670,672,675,678,680],{"class":127,"line":293},[125,655,656],{"class":146},"response ",[125,658,193],{"class":165},[125,660,661],{"class":146}," requests.post(",[125,663,664],{"class":142},"\"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\"",[125,666,230],{"class":146},[125,668,669],{"class":284},"json",[125,671,193],{"class":165},[125,673,674],{"class":146},"payload, ",[125,676,677],{"class":284},"headers",[125,679,193],{"class":165},[125,681,682],{"class":146},"headers)\n",[125,684,685,688,691,693,696,698],{"class":127,"line":304},[125,686,687],{"class":135},"print",[125,689,690],{"class":146},"(response.json()[",[125,692,334],{"class":142},[125,694,695],{"class":146},"][",[125,697,370],{"class":142},[125,699,379],{"class":146},[10,701,702,703,705],{},"保存返回的 ",[46,704,465],{},"，之后需要该形象出镜的视频请求都可以使用它。",[10,707,708,712],{},[709,710,711],"strong",{},"照片要求："," 建议使用单人、清晰、正面的肖像，以获得更好的效果。支持 JPEG、PNG、WEBP 和 HEIC，文件不超过 10 MB。",[14,714,716],{"id":715},"adjust-avatar-framing","调整形象取景",[10,718,719,720,722],{},"专属形象会返回三个画幅的当前取景。先读取 ",[46,721,109],{}," 返回的值，每次调整一个画幅，并提交全部五个必填字段：",[116,724,726],{"className":118,"code":725,"language":120,"meta":121,"style":121},"curl -s -X POST -H \"X-API-Key: $VISIONSTORY_API_KEY\" -H \"Content-Type: application\u002Fjson\" -d '{\"avatar_id\":\"YOUR_AVATAR_ID\",\"aspect_ratio\":\"9:16\",\"zoom\":1.2,\"offset_x\":0,\"offset_y\":-0.25}' https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\u002Fframing\n",[46,727,728],{"__ignoreMap":121},[125,729,730,732,734,737,740,742,744,746,748,750,752,754,757],{"class":127,"line":128},[125,731,132],{"class":131},[125,733,136],{"class":135},[125,735,736],{"class":135}," -X",[125,738,739],{"class":142}," POST",[125,741,139],{"class":135},[125,743,143],{"class":142},[125,745,147],{"class":146},[125,747,150],{"class":142},[125,749,139],{"class":135},[125,751,511],{"class":142},[125,753,514],{"class":135},[125,755,756],{"class":142}," '{\"avatar_id\":\"YOUR_AVATAR_ID\",\"aspect_ratio\":\"9:16\",\"zoom\":1.2,\"offset_x\":0,\"offset_y\":-0.25}'",[125,758,759],{"class":142}," https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\u002Fframing\n",[10,761,762,765,766,769,770,773,774,777,778,781,782,785],{},[46,763,764],{},"zoom=1"," 表示在源图内能够完整容纳所选画幅的最宽取景；数值越大，人物越近。",[46,767,768],{},"offset_x"," 和 ",[46,771,772],{},"offset_y"," 的范围都是 ",[46,775,776],{},"-1"," 到 ",[46,779,780],{},"1","，其中 ",[46,783,784],{},"0"," 表示居中。API 会确保取景框位于源图范围内，确认其中存在清晰人脸后保存，并用于该画幅之后生成的视频。",[10,787,788,789,792,793,444,796,769,798,800,801,804,805,808,809,812,813,816,817,819],{},"只能调整当前账户拥有的形象。缺少源图尺寸的旧形象可能返回 ",[46,790,791],{},"framing_unavailable","。源图过小、无法用于某个画幅时，该画幅的 ",[46,794,795],{},"zoom",[46,797,768],{},[46,799,772],{}," 返回 ",[46,802,803],{},"null","；其 ",[46,806,807],{},"image_url"," 仍可使用，其他画幅也可能仍可调整。写回构图前请逐一检查画幅。如果 zoom 使裁剪区域过小，",[46,810,811],{},"400"," 响应的 details 中会提供 ",[46,814,815],{},"max_zoom","。当 ",[46,818,815],{}," 为 null 时，请使用更大的源图重新创建形象，或选择构图参数不为空的画幅。",[14,821,823],{"id":822},"use-an-avatar-in-a-talking-video","在数字人视频中使用形象",[10,825,826,827,487],{},"创建视频时传入 ",[46,828,465],{},[116,830,833],{"className":831,"code":832,"language":669,"meta":121,"style":121},"language-json shiki shiki-themes github-light github-dark","{\n  \"model_id\": \"vs_character_v4\",\n  \"avatar_id\": \"YOUR_AVATAR_ID\",\n  \"text_script\": { \"text\": \"Hello!\", \"voice_id\": \"YOUR_VOICE_ID\" }\n}\n",[46,834,835,840,852,864,893],{"__ignoreMap":121},[125,836,837],{"class":127,"line":128},[125,838,839],{"class":146},"{\n",[125,841,842,845,847,850],{"class":127,"line":172},[125,843,844],{"class":135},"  \"model_id\"",[125,846,224],{"class":146},[125,848,849],{"class":142},"\"vs_character_v4\"",[125,851,278],{"class":146},[125,853,854,857,859,862],{"class":127,"line":180},[125,855,856],{"class":135},"  \"avatar_id\"",[125,858,224],{"class":146},[125,860,861],{"class":142},"\"YOUR_AVATAR_ID\"",[125,863,278],{"class":146},[125,865,866,869,872,875,877,880,882,885,887,890],{"class":127,"line":187},[125,867,868],{"class":135},"  \"text_script\"",[125,870,871],{"class":146},": { ",[125,873,874],{"class":135},"\"text\"",[125,876,224],{"class":146},[125,878,879],{"class":142},"\"Hello!\"",[125,881,230],{"class":146},[125,883,884],{"class":135},"\"voice_id\"",[125,886,224],{"class":146},[125,888,889],{"class":142},"\"YOUR_VOICE_ID\"",[125,891,892],{"class":146}," }\n",[125,894,895],{"class":127,"line":211},[125,896,241],{"class":146},[10,898,899,900,459],{},"完整的生成、轮询和下载流程见",[901,902,904],"a",{"href":903},"\u002Fguides\u002Fquick-start","快速开始",[14,906,908],{"id":907},"delete-a-custom-avatar","删除专属形象",[10,910,911],{},"只能删除你自己的专属形象；删除不会影响此前已使用该形象生成的视频：",[116,913,915],{"className":118,"code":914,"language":120,"meta":121,"style":121},"curl -s -X DELETE -H \"X-API-Key: $VISIONSTORY_API_KEY\" \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar?avatar_id=YOUR_AVATAR_ID\"\n",[46,916,917],{"__ignoreMap":121},[125,918,919,921,923,925,928,930,932,934,936],{"class":127,"line":128},[125,920,132],{"class":131},[125,922,136],{"class":135},[125,924,736],{"class":135},[125,926,927],{"class":142}," DELETE",[125,929,139],{"class":135},[125,931,143],{"class":142},[125,933,147],{"class":146},[125,935,150],{"class":142},[125,937,938],{"class":142}," \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar?avatar_id=YOUR_AVATAR_ID\"\n",[14,940,942],{"id":941},"related-visionstory-api-guides","相关 VisionStory API 指南",[944,945,946,954,959,966],"ul",{},[947,948,949,953],"li",{},[901,950,952],{"href":951},"\u002Fguides\u002Fvoices","声音"," — 选择或克隆数字人使用的声音。",[947,955,956,958],{},[901,957,904],{"href":903}," — 生成第一个视频。",[947,960,961,965],{},[901,962,964],{"href":963},"\u002Freference\u002Favatars\u002Fupdate-avatar-framing","形象取景 API 参考"," — 查看准确的取景字段、取值范围、响应和错误说明。",[947,967,968,972],{},[901,969,971],{"href":970},"\u002Freference","API 参考"," — 查看完整请求和响应结构。",[974,975,976],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}",{"title":121,"searchDepth":172,"depth":172,"links":978},[979,980,981,982,983,984,985],{"id":16,"depth":172,"text":17},{"id":102,"depth":172,"text":103},{"id":476,"depth":172,"text":477},{"id":715,"depth":172,"text":716},{"id":822,"depth":172,"text":823},{"id":907,"depth":172,"text":908},{"id":941,"depth":172,"text":942},"分页查询数字人形象、创建可复用的专属形象、调整各画幅的取景，并在 VisionStory 视频请求中使用其 avatar_id。","md",{},{"title":990,"order":180},"数字人形象","\u002Fguides-zh\u002Favatars",{"title":5,"description":986},"guides-zh\u002Favatars","KiX11OG4Vu7T-XopKehIuw2hRtHf8Fvltauiav-GHZE","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">curl\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -s\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -H\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"X-API-Key: \u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">$VISIONSTORY_API_KEY\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars?is_public=false&limit=20\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> os\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">headers \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"X-API-Key\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: os.environ[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"VISIONSTORY_API_KEY\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">params \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"is_public\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">False\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">, \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"limit\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">20\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">while\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> True\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    response \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests.get(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatars\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">        headers\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">headers,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">        params\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">params,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">        timeout\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">10\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    )\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    data \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> response.json()[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">    for\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> avatar \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">in\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> data[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"avatars\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">        print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(avatar[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">], avatar[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"default_voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">])\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">    if\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> not\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> data[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"next_cursor\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">        break\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    params[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"cursor\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">] \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> data[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"next_cursor\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">curl\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -s\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -H\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"X-API-Key: \u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">$VISIONSTORY_API_KEY\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -H\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"Content-Type: application\u002Fjson\"\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -d\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> '{\"img_url\": \"https:\u002F\u002Fyour.site\u002Fportrait.jpg\"}'\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> base64\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> os\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">headers \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"X-API-Key\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: os.environ[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"VISIONSTORY_API_KEY\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">with\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> open\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"\u002Fpath\u002Fto\u002Fimage.jpg\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">, \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"rb\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">) \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">as\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> f:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    encoded \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> base64.b64encode(f.read()).decode(\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"utf-8\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">payload \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"inline_data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"mime_type\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"image\u002Fjpg\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">, \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: encoded}}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">response \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests.post(\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">, \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">json\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">payload, \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">headers\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">headers)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(response.json()[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">][\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">])\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">curl\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -s\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -X\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> POST\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -H\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"X-API-Key: \u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">$VISIONSTORY_API_KEY\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -H\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"Content-Type: application\u002Fjson\"\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -d\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> '{\"avatar_id\":\"YOUR_AVATAR_ID\",\"aspect_ratio\":\"9:16\",\"zoom\":1.2,\"offset_x\":0,\"offset_y\":-0.25}'\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\u002Fframing\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"model_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"vs_character_v4\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"avatar_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"YOUR_AVATAR_ID\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"text_script\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: { \u003C\u002Fspan>\u003Cspan style=\"color:#7EE787\">\"text\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Hello!\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">, \u003C\u002Fspan>\u003Cspan style=\"color:#7EE787\">\"voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"YOUR_VOICE_ID\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> }\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">curl\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -s\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -X\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> DELETE\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -H\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"X-API-Key: \u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">$VISIONSTORY_API_KEY\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar?avatar_id=YOUR_AVATAR_ID\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1790231923838]