[{"data":1,"prerenderedAt":1001},["ShallowReactive",2],{"guide-\u002Fguides\u002Fquick-start":3,"developer-code-eb0qrl":987,"developer-code-34eaj7":988,"developer-code-1w80f9x":989,"developer-code-1wjk1yk":990,"developer-code-1obeumo":991,"developer-code-1ag7cua":992,"developer-code-14f04zz":993,"developer-code-1tp71zs":994,"developer-code-1xdn30c":995,"developer-code-yoowr8":996,"developer-code-1xbw2pz":997,"developer-code-1sctawa":998,"developer-code-1m51tx2":999,"developer-code-1cqt0k1":1000},{"id":4,"title":5,"body":6,"description":978,"extension":979,"meta":980,"navigation":981,"path":983,"seo":984,"stem":985,"__hash__":986},"guides\u002Fguides\u002Fquick-start.md","Talking Avatar Video API Quickstart",{"type":7,"value":8,"toc":964},"minimark",[9,13,18,34,45,48,75,82,85,121,137,141,148,222,226,229,245,287,290,293,314,317,347,355,358,365,390,393,451,454,463,467,474,590,631,654,658,661,691,749,752,756,769,790,794,797,931,935,960],[10,11,12],"p",{},"This quickstart creates a complete AI talking-avatar video in five steps. You will authenticate the VisionStory API, submit a text script, poll the asynchronous job, and save the generated MP4 locally.",[14,15,17],"h2",{"id":16},"_1-create-a-visionstory-api-key","1. Create a VisionStory API key",[10,19,20,21,28,29,33],{},"Sign up and create an API key on the ",[22,23,27],"a",{"href":24,"rel":25},"https:\u002F\u002Fdevelopers.visionstory.ai\u002Fapi-keys",[26],"nofollow","VisionStory API keys page",". Send it with every request in the ",[30,31,32],"code",{},"X-API-Key"," header:",[35,36,43],"pre",{"className":37,"code":39,"filename":40,"language":41,"meta":42},[38],"language-text","X-API-Key: $VISIONSTORY_API_KEY\n","Request header","text","",[30,44,39],{"__ignoreMap":42},[10,46,47],{},"Keep the key on your server and never expose it in browser code or a public repository. The examples below read it from an environment variable:",[35,49,53],{"className":50,"code":51,"language":52,"meta":42,"style":42},"language-bash shiki shiki-themes github-light github-dark","export VISIONSTORY_API_KEY=\"sk-vs-xxxxxxxxxxxxxxxxxxx\"\n","bash",[30,54,55],{"__ignoreMap":42},[56,57,60,64,68,71],"span",{"class":58,"line":59},"line",1,[56,61,63],{"class":62},"szBVR","export",[56,65,67],{"class":66},"sVt8B"," VISIONSTORY_API_KEY",[56,69,70],{"class":62},"=",[56,72,74],{"class":73},"sZZnC","\"sk-vs-xxxxxxxxxxxxxxxxxxx\"\n",[10,76,77,78,81],{},"VisionStory CLI users can instead run ",[30,79,80],{},"visionstory login"," after installation. It hides the input, verifies the key,\nand saves it for future CLI sessions without putting the secret in shell history.",[10,83,84],{},"Before starting a paid generation, verify the key with a read-only request:",[35,86,88],{"className":50,"code":87,"language":52,"meta":42,"style":42},"curl -s -H \"X-API-Key: $VISIONSTORY_API_KEY\" \\\n  https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fbilling\u002Fcredits\n",[30,89,90,115],{"__ignoreMap":42},[56,91,92,96,100,103,106,109,112],{"class":58,"line":59},[56,93,95],{"class":94},"sScJk","curl",[56,97,99],{"class":98},"sj4cs"," -s",[56,101,102],{"class":98}," -H",[56,104,105],{"class":73}," \"X-API-Key: ",[56,107,108],{"class":66},"$VISIONSTORY_API_KEY",[56,110,111],{"class":73},"\"",[56,113,114],{"class":98}," \\\n",[56,116,118],{"class":58,"line":117},2,[56,119,120],{"class":73},"  https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fbilling\u002Fcredits\n",[10,122,123,124,127,128,131,132,136],{},"A successful response includes your plan and remaining credits; the ",[30,125,126],{},"remaining"," value is your current VisionStory\ncredit balance. A ",[30,129,130],{},"401"," response means the key is missing, expired, or no longer valid; create or replace it at\n",[22,133,135],{"href":24,"rel":134},[26],"API keys page"," before continuing.",[14,138,140],{"id":139},"_2-choose-an-api-client","2. Choose an API client",[10,142,143,144,147],{},"Start with the option that matches your task. You can switch later because every interface uses the same VisionStory API and ",[30,145,146],{},"VISIONSTORY_API_KEY",".",[149,150,151,164],"table",{},[152,153,154],"thead",{},[155,156,157,161],"tr",{},[158,159,160],"th",{},"Your goal",[158,162,163],{},"Recommended start",[165,166,167,179,189,202,212],"tbody",{},[155,168,169,173],{},[170,171,172],"td",{},"Add VisionStory to a Python application",[170,174,175],{},[176,177,178],"strong",{},"Python SDK",[155,180,181,184],{},[170,182,183],{},"Run one-off commands, shell scripts, or CI jobs",[170,185,186],{},[176,187,188],{},"VisionStory CLI",[155,190,191,194],{},[170,192,193],{},"Let an AI agent use the complete API as tools",[170,195,196],{},[176,197,198],{},[22,199,201],{"href":200},"\u002Fguides\u002Ffor-agents#connect-the-visionstory-mcp-server","MCP server",[155,203,204,207],{},[170,205,206],{},"Give a coding agent the focused talking-avatar workflow",[170,208,209],{},[176,210,211],{},"Agent Skill",[155,213,214,217],{},[170,215,216],{},"Integrate from another backend language",[170,218,219],{},[176,220,221],{},"REST API",[223,224,178],"h3",{"id":225},"python-sdk",[10,227,228],{},"Install the typed, zero-dependency Python client:",[35,230,232],{"className":50,"code":231,"language":52,"meta":42,"style":42},"pip install visionstory\n",[30,233,234],{"__ignoreMap":42},[56,235,236,239,242],{"class":58,"line":59},[56,237,238],{"class":94},"pip",[56,240,241],{"class":73}," install",[56,243,244],{"class":73}," visionstory\n",[35,246,250],{"className":247,"code":248,"language":249,"meta":42,"style":42},"language-python shiki shiki-themes github-light github-dark","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()  # reads VISIONSTORY_API_KEY\n","python",[30,251,252,266,272],{"__ignoreMap":42},[56,253,254,257,260,263],{"class":58,"line":59},[56,255,256],{"class":62},"from",[56,258,259],{"class":66}," visionstory ",[56,261,262],{"class":62},"import",[56,264,265],{"class":66}," VisionStoryClient\n",[56,267,268],{"class":58,"line":117},[56,269,271],{"emptyLinePlaceholder":270},true,"\n",[56,273,275,278,280,283],{"class":58,"line":274},3,[56,276,277],{"class":66},"client ",[56,279,70],{"class":62},[56,281,282],{"class":66}," VisionStoryClient.from_env()  ",[56,284,286],{"class":285},"sJ8bj","# reads VISIONSTORY_API_KEY\n",[223,288,188],{"id":289},"visionstory-cli",[10,291,292],{},"Install or upgrade to the latest CLI release in an isolated environment:",[35,294,296],{"className":50,"code":295,"language":52,"meta":42,"style":42},"curl -fsSL https:\u002F\u002Fdevelopers.visionstory.ai\u002Fcli | bash\n",[30,297,298],{"__ignoreMap":42},[56,299,300,302,305,308,311],{"class":58,"line":59},[56,301,95],{"class":94},[56,303,304],{"class":98}," -fsSL",[56,306,307],{"class":73}," https:\u002F\u002Fdevelopers.visionstory.ai\u002Fcli",[56,309,310],{"class":62}," |",[56,312,313],{"class":94}," bash\n",[10,315,316],{},"After restarting the terminal if prompted, verify authentication and discover valid resource IDs:",[35,318,320],{"className":50,"code":319,"language":52,"meta":42,"style":42},"visionstory credits\nvisionstory avatars --is-public\nvisionstory voices\n",[30,321,322,330,340],{"__ignoreMap":42},[56,323,324,327],{"class":58,"line":59},[56,325,326],{"class":94},"visionstory",[56,328,329],{"class":73}," credits\n",[56,331,332,334,337],{"class":58,"line":117},[56,333,326],{"class":94},[56,335,336],{"class":73}," avatars",[56,338,339],{"class":98}," --is-public\n",[56,341,342,344],{"class":58,"line":274},[56,343,326],{"class":94},[56,345,346],{"class":73}," voices\n",[10,348,349,350,354],{},"See the ",[22,351,353],{"href":352},"\u002Fguides\u002Fcli","CLI guide"," for every command.",[223,356,211],{"id":357},"agent-skill",[10,359,360,361,364],{},"The focused talking-avatar Agent Skill ships a ",[30,362,363],{},"SKILL.md"," plus a dependency-free Python helper that handles authentication, base64 encoding, polling, and downloads. It auto-detects supported coding agents:",[35,366,368],{"className":50,"code":367,"language":52,"meta":42,"style":42},"npx skills add visionstory-ai\u002Fskills --skill visionstory-api\n",[30,369,370],{"__ignoreMap":42},[56,371,372,375,378,381,384,387],{"class":58,"line":59},[56,373,374],{"class":94},"npx",[56,376,377],{"class":73}," skills",[56,379,380],{"class":73}," add",[56,382,383],{"class":73}," visionstory-ai\u002Fskills",[56,385,386],{"class":98}," --skill",[56,388,389],{"class":73}," visionstory-api\n",[10,391,392],{},"Then create a video in one command:",[35,394,396],{"className":50,"code":395,"language":52,"meta":42,"style":42},"python3 .agents\u002Fskills\u002Fvisionstory-api\u002Fscripts\u002Fvisionstory_api.py create-video \\\n  --avatar-id YOUR_AVATAR_ID \\\n  --text \"Hello from VisionStory.\" \\\n  --voice-id YOUR_VOICE_ID \\\n  --output result.mp4\n",[30,397,398,411,421,431,442],{"__ignoreMap":42},[56,399,400,403,406,409],{"class":58,"line":59},[56,401,402],{"class":94},"python3",[56,404,405],{"class":73}," .agents\u002Fskills\u002Fvisionstory-api\u002Fscripts\u002Fvisionstory_api.py",[56,407,408],{"class":73}," create-video",[56,410,114],{"class":98},[56,412,413,416,419],{"class":58,"line":117},[56,414,415],{"class":98},"  --avatar-id",[56,417,418],{"class":73}," YOUR_AVATAR_ID",[56,420,114],{"class":98},[56,422,423,426,429],{"class":58,"line":274},[56,424,425],{"class":98},"  --text",[56,427,428],{"class":73}," \"Hello from VisionStory.\"",[56,430,114],{"class":98},[56,432,434,437,440],{"class":58,"line":433},4,[56,435,436],{"class":98},"  --voice-id",[56,438,439],{"class":73}," YOUR_VOICE_ID",[56,441,114],{"class":98},[56,443,445,448],{"class":58,"line":444},5,[56,446,447],{"class":98},"  --output",[56,449,450],{"class":73}," result.mp4\n",[223,452,221],{"id":453},"rest-api",[10,455,456,457,459,460,147],{},"Call the API directly with ",[30,458,95],{}," or any HTTP client. The complete Python example at the end of this guide only needs ",[30,461,462],{},"requests",[14,464,466],{"id":465},"_3-generate-a-talking-avatar-video","3. Generate a talking avatar video",[10,468,469,470,473],{},"Submit a text script with a public avatar and voice. The request returns a ",[30,471,472],{},"video_id"," immediately while generation continues asynchronously:",[35,475,477],{"className":50,"code":476,"language":52,"meta":42,"style":42},"curl -s \\\n  -H \"X-API-Key: $VISIONSTORY_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"model_id\": \"vs_character_v4\",\n    \"avatar_id\": \"YOUR_AVATAR_ID\",\n    \"client_request_id\": \"YOUR_UNIQUE_REQUEST_ID\",\n    \"text_script\": {\n      \"text\": \"Hello World, this is my first test video.\",\n      \"voice_id\": \"YOUR_VOICE_ID\",\n      \"speech_rate\": \"normal\"\n    },\n    \"aspect_ratio\": \"9:16\",\n    \"resolution\": \"720p\"\n  }' \\\n  https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo\n",[30,478,479,487,500,509,517,522,528,534,540,546,552,558,564,570,576,584],{"__ignoreMap":42},[56,480,481,483,485],{"class":58,"line":59},[56,482,95],{"class":94},[56,484,99],{"class":98},[56,486,114],{"class":98},[56,488,489,492,494,496,498],{"class":58,"line":117},[56,490,491],{"class":98},"  -H",[56,493,105],{"class":73},[56,495,108],{"class":66},[56,497,111],{"class":73},[56,499,114],{"class":98},[56,501,502,504,507],{"class":58,"line":274},[56,503,491],{"class":98},[56,505,506],{"class":73}," \"Content-Type: application\u002Fjson\"",[56,508,114],{"class":98},[56,510,511,514],{"class":58,"line":433},[56,512,513],{"class":98},"  -d",[56,515,516],{"class":73}," '{\n",[56,518,519],{"class":58,"line":444},[56,520,521],{"class":73},"    \"model_id\": \"vs_character_v4\",\n",[56,523,525],{"class":58,"line":524},6,[56,526,527],{"class":73},"    \"avatar_id\": \"YOUR_AVATAR_ID\",\n",[56,529,531],{"class":58,"line":530},7,[56,532,533],{"class":73},"    \"client_request_id\": \"YOUR_UNIQUE_REQUEST_ID\",\n",[56,535,537],{"class":58,"line":536},8,[56,538,539],{"class":73},"    \"text_script\": {\n",[56,541,543],{"class":58,"line":542},9,[56,544,545],{"class":73},"      \"text\": \"Hello World, this is my first test video.\",\n",[56,547,549],{"class":58,"line":548},10,[56,550,551],{"class":73},"      \"voice_id\": \"YOUR_VOICE_ID\",\n",[56,553,555],{"class":58,"line":554},11,[56,556,557],{"class":73},"      \"speech_rate\": \"normal\"\n",[56,559,561],{"class":58,"line":560},12,[56,562,563],{"class":73},"    },\n",[56,565,567],{"class":58,"line":566},13,[56,568,569],{"class":73},"    \"aspect_ratio\": \"9:16\",\n",[56,571,573],{"class":58,"line":572},14,[56,574,575],{"class":73},"    \"resolution\": \"720p\"\n",[56,577,579,582],{"class":58,"line":578},15,[56,580,581],{"class":73},"  }'",[56,583,114],{"class":98},[56,585,587],{"class":58,"line":586},16,[56,588,589],{"class":73},"  https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo\n",[35,591,595],{"className":592,"code":593,"language":594,"meta":42,"style":42},"language-json shiki shiki-themes github-light github-dark","{\n  \"data\": {\n    \"video_id\": \"YOUR_VIDEO_ID\"\n  }\n}\n","json",[30,596,597,602,610,621,626],{"__ignoreMap":42},[56,598,599],{"class":58,"line":59},[56,600,601],{"class":66},"{\n",[56,603,604,607],{"class":58,"line":117},[56,605,606],{"class":98},"  \"data\"",[56,608,609],{"class":66},": {\n",[56,611,612,615,618],{"class":58,"line":274},[56,613,614],{"class":98},"    \"video_id\"",[56,616,617],{"class":66},": ",[56,619,620],{"class":73},"\"YOUR_VIDEO_ID\"\n",[56,622,623],{"class":58,"line":433},[56,624,625],{"class":66},"  }\n",[56,627,628],{"class":58,"line":444},[56,629,630],{"class":66},"}\n",[10,632,633,634,637,638,641,642,645,646,649,650,653],{},"Before building a production integration, discover current IDs instead of hardcoding them: ",[30,635,636],{},"GET \u002Fapi\u002Fv1\u002Fmodels",", ",[30,639,640],{},"GET \u002Fapi\u002Fv1\u002Favatars",", and ",[30,643,644],{},"GET \u002Fapi\u002Fv1\u002Fvoices",". To use your own audio, send an ",[30,647,648],{},"audio_script"," in place of ",[30,651,652],{},"text_script"," — never both.",[14,655,657],{"id":656},"_4-poll-the-video-generation-job","4. Poll the video generation job",[10,659,660],{},"Query the task every 5 seconds until it reaches a final state:",[35,662,664],{"className":50,"code":663,"language":52,"meta":42,"style":42},"curl -s \\\n  -H \"X-API-Key: $VISIONSTORY_API_KEY\" \\\n  \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo?video_id=YOUR_VIDEO_ID\"\n",[30,665,666,674,686],{"__ignoreMap":42},[56,667,668,670,672],{"class":58,"line":59},[56,669,95],{"class":94},[56,671,99],{"class":98},[56,673,114],{"class":98},[56,675,676,678,680,682,684],{"class":58,"line":117},[56,677,491],{"class":98},[56,679,105],{"class":73},[56,681,108],{"class":66},[56,683,111],{"class":73},[56,685,114],{"class":98},[56,687,688],{"class":58,"line":274},[56,689,690],{"class":73},"  \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo?video_id=YOUR_VIDEO_ID\"\n",[149,692,693,703],{},[152,694,695],{},[155,696,697,700],{},[158,698,699],{},"status",[158,701,702],{},"Meaning",[165,704,705,715,725,739],{},[155,706,707,712],{},[170,708,709],{},[30,710,711],{},"queued",[170,713,714],{},"Accepted, waiting for a worker",[155,716,717,722],{},[170,718,719],{},[30,720,721],{},"creating",[170,723,724],{},"Generating",[155,726,727,732],{},[170,728,729],{},[30,730,731],{},"created",[170,733,734,735,738],{},"Done — ",[30,736,737],{},"video_url"," is ready",[155,740,741,746],{},[170,742,743],{},[30,744,745],{},"failed",[170,747,748],{},"Generation failed — stop polling and inspect the error",[10,750,751],{},"Avoid polling faster than every 5 seconds, and give up after about 10 minutes.",[14,753,755],{"id":754},"_5-download-the-generated-mp4","5. Download the generated MP4",[10,757,758,759,761,762,764,765,768],{},"When the status is ",[30,760,731],{},", the response carries a ",[30,763,737],{},". Completed videos are retained for ",[176,766,767],{},"7 days",", so download the file if you need permanent storage:",[35,770,772],{"className":50,"code":771,"language":52,"meta":42,"style":42},"curl -sL -o result.mp4 \"\u003Cvideo_url from the response>\"\n",[30,773,774],{"__ignoreMap":42},[56,775,776,778,781,784,787],{"class":58,"line":59},[56,777,95],{"class":94},[56,779,780],{"class":98}," -sL",[56,782,783],{"class":98}," -o",[56,785,786],{"class":73}," result.mp4",[56,788,789],{"class":73}," \"\u003Cvideo_url from the response>\"\n",[14,791,793],{"id":792},"complete-python-sdk-example","Complete Python SDK example",[10,795,796],{},"With the SDK, the whole flow is a few lines:",[35,798,800],{"className":247,"code":799,"language":249,"meta":42,"style":42},"from pathlib import Path\nfrom visionstory import VisionStoryClient, build_video_payload\n\nclient = VisionStoryClient.from_env()\npayload = build_video_payload(\n    avatar_id=\"YOUR_AVATAR_ID\",\n    text=\"Hello World, this is my first test video.\",\n    voice_id=\"YOUR_VOICE_ID\",\n)\nvideo = client.generate_video(payload)\nclient.download(video[\"video_url\"], Path(\"result.mp4\"))\nprint(\"saved result.mp4\")\n",[30,801,802,814,825,829,838,848,862,874,886,891,901,918],{"__ignoreMap":42},[56,803,804,806,809,811],{"class":58,"line":59},[56,805,256],{"class":62},[56,807,808],{"class":66}," pathlib ",[56,810,262],{"class":62},[56,812,813],{"class":66}," Path\n",[56,815,816,818,820,822],{"class":58,"line":117},[56,817,256],{"class":62},[56,819,259],{"class":66},[56,821,262],{"class":62},[56,823,824],{"class":66}," VisionStoryClient, build_video_payload\n",[56,826,827],{"class":58,"line":274},[56,828,271],{"emptyLinePlaceholder":270},[56,830,831,833,835],{"class":58,"line":433},[56,832,277],{"class":66},[56,834,70],{"class":62},[56,836,837],{"class":66}," VisionStoryClient.from_env()\n",[56,839,840,843,845],{"class":58,"line":444},[56,841,842],{"class":66},"payload ",[56,844,70],{"class":62},[56,846,847],{"class":66}," build_video_payload(\n",[56,849,850,854,856,859],{"class":58,"line":524},[56,851,853],{"class":852},"s4XuR","    avatar_id",[56,855,70],{"class":62},[56,857,858],{"class":73},"\"YOUR_AVATAR_ID\"",[56,860,861],{"class":66},",\n",[56,863,864,867,869,872],{"class":58,"line":530},[56,865,866],{"class":852},"    text",[56,868,70],{"class":62},[56,870,871],{"class":73},"\"Hello World, this is my first test video.\"",[56,873,861],{"class":66},[56,875,876,879,881,884],{"class":58,"line":536},[56,877,878],{"class":852},"    voice_id",[56,880,70],{"class":62},[56,882,883],{"class":73},"\"YOUR_VOICE_ID\"",[56,885,861],{"class":66},[56,887,888],{"class":58,"line":542},[56,889,890],{"class":66},")\n",[56,892,893,896,898],{"class":58,"line":548},[56,894,895],{"class":66},"video ",[56,897,70],{"class":62},[56,899,900],{"class":66}," client.generate_video(payload)\n",[56,902,903,906,909,912,915],{"class":58,"line":554},[56,904,905],{"class":66},"client.download(video[",[56,907,908],{"class":73},"\"video_url\"",[56,910,911],{"class":66},"], Path(",[56,913,914],{"class":73},"\"result.mp4\"",[56,916,917],{"class":66},"))\n",[56,919,920,923,926,929],{"class":58,"line":560},[56,921,922],{"class":98},"print",[56,924,925],{"class":66},"(",[56,927,928],{"class":73},"\"saved result.mp4\"",[56,930,890],{"class":66},[14,932,934],{"id":933},"related-visionstory-api-guides","Related VisionStory API guides",[936,937,938,946,953],"ul",{},[939,940,941,945],"li",{},[22,942,944],{"href":943},"\u002Fguides\u002Foverview","Read the overview"," for core resources, response envelopes, and model choices.",[939,947,948,952],{},[22,949,951],{"href":950},"\u002Freference","Explore the API reference"," for request schemas, parameters, and responses.",[939,954,955,959],{},[22,956,958],{"href":24,"rel":957},[26],"Get an API key"," when you are ready to run a real request.",[961,962,963],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}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 .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 .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}",{"title":42,"searchDepth":117,"depth":117,"links":965},[966,967,973,974,975,976,977],{"id":16,"depth":117,"text":17},{"id":139,"depth":117,"text":140,"children":968},[969,970,971,972],{"id":225,"depth":274,"text":178},{"id":289,"depth":274,"text":188},{"id":357,"depth":274,"text":211},{"id":453,"depth":274,"text":221},{"id":465,"depth":117,"text":466},{"id":656,"depth":117,"text":657},{"id":754,"depth":117,"text":755},{"id":792,"depth":117,"text":793},{"id":933,"depth":117,"text":934},"Generate and download your first AI talking avatar video with the VisionStory REST API or Python SDK, including authentication, polling, and storage.","md",{},{"title":982,"order":117},"Quick start","\u002Fguides\u002Fquick-start",{"title":5,"description":978},"guides\u002Fquick-start","Q_23l_lEjzZaRvMsjSCBjUl-FFRuqht4rJzKJeLfJlE","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan>X-API-Key: $VISIONSTORY_API_KEY\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>\u003C\u002Fspan>\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\">export\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VISIONSTORY_API_KEY\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"sk-vs-xxxxxxxxxxxxxxxxxxx\"\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:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">  https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fbilling\u002Fcredits\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\">pip\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> install\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> visionstory\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\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient.from_env()  \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># reads VISIONSTORY_API_KEY\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\"> -fsSL\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> https:\u002F\u002Fdevelopers.visionstory.ai\u002Fcli\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> |\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\"> bash\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\">visionstory\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> credits\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">visionstory\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> avatars\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --is-public\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">visionstory\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> voices\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\">npx\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> skills\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> add\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> visionstory-ai\u002Fskills\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --skill\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> visionstory-api\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\">python3\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> .agents\u002Fskills\u002Fvisionstory-api\u002Fscripts\u002Fvisionstory_api.py\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> create-video\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  --avatar-id\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> YOUR_AVATAR_ID\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  --text\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"Hello from VisionStory.\"\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  --voice-id\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> YOUR_VOICE_ID\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  --output\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> result.mp4\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:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\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:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  -H\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"Content-Type: application\u002Fjson\"\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">  -d\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> '{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"model_id\": \"vs_character_v4\",\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"avatar_id\": \"YOUR_AVATAR_ID\",\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"client_request_id\": \"YOUR_UNIQUE_REQUEST_ID\",\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"text_script\": {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">      \"text\": \"Hello World, this is my first test video.\",\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">      \"voice_id\": \"YOUR_VOICE_ID\",\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">      \"speech_rate\": \"normal\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"aspect_ratio\": \"9:16\",\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"resolution\": \"720p\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">  }'\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">  https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo\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\">  \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"video_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"YOUR_VIDEO_ID\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\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:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\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:#FF7B72\"> \\\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">  \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo?video_id=YOUR_VIDEO_ID\"\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\"> -sL\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -o\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> result.mp4\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"<video_url from the response>\"\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\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> pathlib \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> Path\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient, build_video_payload\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient.from_env()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">payload \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> build_video_payload(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    avatar_id\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\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:#FFA657\">    text\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Hello World, this is my first test video.\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    voice_id\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\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\">\u003Cspan style=\"color:#E6EDF3\">video \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.generate_video(payload)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client.download(video[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"video_url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">], Path(\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"result.mp4\"\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\">(\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"saved result.mp4\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1790231923838]