[{"data":1,"prerenderedAt":1005},["ShallowReactive",2],{"guide-\u002Fguides\u002Favatars":3,"developer-code-71rrns":998,"developer-code-1r19c2f":999,"developer-code-1dpm3n2":1000,"developer-code-1mezl69":1001,"developer-code-1oilrhu":1002,"developer-code-nntzbn":1003,"developer-code-10t76cq":1004},{"id":4,"title":5,"body":6,"description":989,"extension":990,"meta":991,"navigation":992,"path":994,"seo":995,"stem":996,"__hash__":997},"guides\u002Fguides\u002Favatars.md","AI Avatar API",{"type":7,"value":8,"toc":980},"minimark",[9,13,18,100,104,115,154,422,459,473,477,487,520,526,700,706,713,717,723,760,786,821,825,831,899,908,912,915,942,946,976],[10,11,12],"p",{},"The VisionStory AI Avatar API provides the on-screen character for a talking-avatar video. List your own avatars or the public library, create a reusable custom avatar from one portrait, and control how an owned avatar is framed in each supported aspect ratio.",[14,15,17],"h2",{"id":16},"ai-avatar-api-endpoints","AI avatar API endpoints",[19,20,21,37],"table",{},[22,23,24],"thead",{},[25,26,27,31,34],"tr",{},[28,29,30],"th",{},"Method",[28,32,33],{},"Path",[28,35,36],{},"What it does",[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],{},"List either owned avatars or the public library, with cursor pagination",[25,58,59,64,69],{},[43,60,61],{},[46,62,63],{},"POST",[43,65,66],{},[46,67,68],{},"\u002Fapi\u002Fv1\u002Favatar",[43,70,71],{},"Create a custom avatar from an image",[25,73,74,78,83],{},[43,75,76],{},[46,77,63],{},[43,79,80],{},[46,81,82],{},"\u002Fapi\u002Fv1\u002Favatar\u002Fframing",[43,84,85],{},"Update one aspect ratio's framing for an owned avatar",[25,87,88,93,97],{},[43,89,90],{},[46,91,92],{},"DELETE",[43,94,95],{},[46,96,68],{},[43,98,99],{},"Delete one of your custom avatars",[14,101,103],{"id":102},"list-owned-or-public-avatars","List owned or public avatars",[10,105,106,107,110,111,114],{},"Each request returns one collection. By default, ",[46,108,109],{},"GET \u002Fapi\u002Fv1\u002Favatars"," lists avatars owned by the authenticated account. Set ",[46,112,113],{},"is_public=true"," to list the public library instead. Results are newest first and use cursor pagination:",[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,230,448,230,451,454,455,458],{},"The response shape is ",[46,426,427],{},"{ \"avatars\": [...], \"next_cursor\": 0 }","; ",[46,430,431],{},"next_cursor=0"," means there are no more pages. ",[46,434,435],{},"limit"," accepts 1–100 and defaults to 20. Owned avatars include their real ",[46,438,439],{},"created_at"," and a three-entry ",[46,442,443],{},"framing"," array ordered ",[46,446,447],{},"9:16",[46,449,450],{},"16:9",[46,452,453],{},"1:1",". Public avatars always return ",[46,456,457],{},"framing: null",".",[10,460,461,462,465,466,469,470,458],{},"Always choose an ",[46,463,464],{},"avatar_id"," from this endpoint instead of hardcoding one. To use the avatar's configured voice, copy its non-empty ",[46,467,468],{},"default_voice_id"," into ",[46,471,472],{},"text_script.voice_id",[14,474,476],{"id":475},"create-an-ai-avatar-from-a-photo","Create an AI avatar from a photo",[10,478,479,480,482,483,486],{},"Send one portrait image, get back an ",[46,481,464],{},". Provide the image as either a public HTTPS URL or base64 ",[46,484,485],{},"inline_data"," — exactly one of the two:",[116,488,490],{"className":118,"code":489,"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,491,492],{"__ignoreMap":121},[125,493,494,496,498,500,502,504,506,508,511,514,517],{"class":127,"line":128},[125,495,132],{"class":131},[125,497,136],{"class":135},[125,499,139],{"class":135},[125,501,143],{"class":142},[125,503,147],{"class":146},[125,505,150],{"class":142},[125,507,139],{"class":135},[125,509,510],{"class":142}," \"Content-Type: application\u002Fjson\"",[125,512,513],{"class":135}," -d",[125,515,516],{"class":142}," '{\"img_url\": \"https:\u002F\u002Fyour.site\u002Fportrait.jpg\"}'",[125,518,519],{"class":142}," https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar\n",[10,521,522,523,525],{},"With a local file, base64-encode it into ",[46,524,485],{},":",[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],{},"Store the returned ",[46,704,464],{}," — you will pass it to every video request that should feature this avatar.",[10,707,708,712],{},[709,710,711],"strong",{},"Photo requirements:"," use a single, clear, front-facing portrait for best results. Supported formats are JPEG, PNG, WEBP, and HEIC, up to 10 MB.",[14,714,716],{"id":715},"adjust-avatar-framing","Adjust avatar framing",[10,718,719,720,722],{},"Owned avatars expose current framing for all three aspect ratios. Start with the values returned by ",[46,721,109],{},", change one ratio at a time, and send all five required fields:",[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,510],{"class":142},[125,753,513],{"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"," uses the widest frame that fits the selected aspect ratio; larger values move closer. ",[46,767,768],{},"offset_x"," and ",[46,771,772],{},"offset_y"," range from ",[46,775,776],{},"-1"," to ",[46,779,780],{},"1",", where ",[46,783,784],{},"0"," is centered. The API keeps the frame inside the source image, verifies that it contains a visible face, saves it, and uses it for later videos in that aspect ratio.",[10,787,788,789,792,793,230,796,798,799,801,802,805,806,809,810,813,814,817,818,820],{},"Only avatars owned by the account can be reframed. Older avatars without source-image dimensions may return ",[46,790,791],{},"framing_unavailable",". A source image that is too small for one aspect ratio returns ",[46,794,795],{},"zoom",[46,797,768],{},", and ",[46,800,772],{}," as ",[46,803,804],{},"null"," for that ratio; its ",[46,807,808],{},"image_url"," remains available and other ratios may still be adjustable. Check each ratio before writing framing back. If a requested zoom makes the crop too small, the ",[46,811,812],{},"400"," response includes ",[46,815,816],{},"max_zoom"," in its details. When ",[46,819,816],{}," is null, create the avatar again with a larger source image or choose a ratio with non-null framing values.",[14,822,824],{"id":823},"use-an-avatar-in-a-talking-video","Use an avatar in a talking video",[10,826,827,828,830],{},"Pass the ",[46,829,464],{}," when creating a video:",[116,832,835],{"className":833,"code":834,"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,836,837,842,854,866,895],{"__ignoreMap":121},[125,838,839],{"class":127,"line":128},[125,840,841],{"class":146},"{\n",[125,843,844,847,849,852],{"class":127,"line":172},[125,845,846],{"class":135},"  \"model_id\"",[125,848,224],{"class":146},[125,850,851],{"class":142},"\"vs_character_v4\"",[125,853,278],{"class":146},[125,855,856,859,861,864],{"class":127,"line":180},[125,857,858],{"class":135},"  \"avatar_id\"",[125,860,224],{"class":146},[125,862,863],{"class":142},"\"YOUR_AVATAR_ID\"",[125,865,278],{"class":146},[125,867,868,871,874,877,879,882,884,887,889,892],{"class":127,"line":187},[125,869,870],{"class":135},"  \"text_script\"",[125,872,873],{"class":146},": { ",[125,875,876],{"class":135},"\"text\"",[125,878,224],{"class":146},[125,880,881],{"class":142},"\"Hello!\"",[125,883,230],{"class":146},[125,885,886],{"class":135},"\"voice_id\"",[125,888,224],{"class":146},[125,890,891],{"class":142},"\"YOUR_VOICE_ID\"",[125,893,894],{"class":146}," }\n",[125,896,897],{"class":127,"line":211},[125,898,241],{"class":146},[10,900,901,902,907],{},"See the ",[903,904,906],"a",{"href":905},"\u002Fguides\u002Fquick-start","Quick start"," for the full generate-poll-download flow.",[14,909,911],{"id":910},"delete-a-custom-avatar","Delete a custom avatar",[10,913,914],{},"Deleting only affects your own custom avatars; videos already generated with it are unaffected:",[116,916,918],{"className":118,"code":917,"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,919,920],{"__ignoreMap":121},[125,921,922,924,926,928,931,933,935,937,939],{"class":127,"line":128},[125,923,132],{"class":131},[125,925,136],{"class":135},[125,927,736],{"class":135},[125,929,930],{"class":142}," DELETE",[125,932,139],{"class":135},[125,934,143],{"class":142},[125,936,147],{"class":146},[125,938,150],{"class":142},[125,940,941],{"class":142}," \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Favatar?avatar_id=YOUR_AVATAR_ID\"\n",[14,943,945],{"id":944},"related-visionstory-api-guides","Related VisionStory API guides",[947,948,949,957,962,969],"ul",{},[950,951,952,956],"li",{},[903,953,955],{"href":954},"\u002Fguides\u002Fvoices","Voices"," — pick or clone the voice your avatar speaks with.",[950,958,959,961],{},[903,960,906],{"href":905}," — generate your first video.",[950,963,964,968],{},[903,965,967],{"href":966},"\u002Freference\u002Favatars\u002Fupdate-avatar-framing","Avatar API reference"," — inspect exact framing fields, bounds, responses, and error details.",[950,970,971,975],{},[903,972,974],{"href":973},"\u002Freference","API reference"," — full request and response schemas.",[977,978,979],"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":981},[982,983,984,985,986,987,988],{"id":16,"depth":172,"text":17},{"id":102,"depth":172,"text":103},{"id":475,"depth":172,"text":476},{"id":715,"depth":172,"text":716},{"id":823,"depth":172,"text":824},{"id":910,"depth":172,"text":911},{"id":944,"depth":172,"text":945},"List and paginate AI avatars, create a reusable custom avatar, adjust its framing for each aspect ratio, and use its avatar_id in VisionStory video requests.","md",{},{"title":993,"order":180},"Avatars","\u002Fguides\u002Favatars",{"title":5,"description":989},"guides\u002Favatars","XVaIKhywbDWaj8Pv62PT4aV4N-cl9Fcrqw4xKT1VAFY","\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]