[{"data":1,"prerenderedAt":787},["ShallowReactive",2],{"guide-\u002Fguides\u002Fsdk":3,"developer-code-1wjk1yk":777,"developer-code-34eaj7":778,"developer-code-1oj8mty":779,"developer-code-1ao897t":780,"developer-code-1h64ruz":781,"developer-code-1qomxzk":782,"developer-code-2qdzci":783,"developer-code-1czdkeo":784,"developer-code-bw2srb":785,"developer-code-1tcriyf":786},{"id":4,"title":5,"body":6,"description":768,"extension":769,"meta":770,"navigation":771,"path":773,"seo":774,"stem":775,"__hash__":776},"guides\u002Fguides\u002Fsdk.md","VisionStory Python SDK",{"type":7,"value":8,"toc":756},"minimark",[9,23,26,31,56,60,71,92,131,138,142,148,308,347,351,361,397,405,409,412,449,453,485,496,500,560,575,579,582,635,645,649,723,727,752],[10,11,12,13,17,18,22],"p",{},"The ",[14,15,16],"code",{},"visionstory"," package is the official Python SDK for the VisionStory API. This ",[19,20,21],"strong",{},"zero-dependency"," client uses only the Python standard library and handles authentication, JSON, base64 uploads, asynchronous polling, errors, and media downloads.",[10,24,25],{},"Requires Python 3.10+.",[27,28,30],"h2",{"id":29},"install-the-visionstory-python-sdk","Install the VisionStory Python SDK",[32,33,38],"pre",{"className":34,"code":35,"language":36,"meta":37,"style":37},"language-bash shiki shiki-themes github-light github-dark","pip install visionstory\n","bash","",[14,39,40],{"__ignoreMap":37},[41,42,45,49,53],"span",{"class":43,"line":44},"line",1,[41,46,48],{"class":47},"sScJk","pip",[41,50,52],{"class":51},"sZZnC"," install",[41,54,55],{"class":51}," visionstory\n",[27,57,59],{"id":58},"authenticate-the-python-client","Authenticate the Python client",[10,61,62,63,70],{},"Create an API key in the ",[64,65,69],"a",{"href":66,"rel":67},"https:\u002F\u002Fwww.visionstory.ai\u002Fopenapi",[68],"nofollow","VisionStory API dashboard"," (available on Pro plans and above), then store it in an environment variable. The client reads the key without putting it in source code:",[32,72,74],{"className":34,"code":73,"language":36,"meta":37,"style":37},"export VISIONSTORY_API_KEY=\"sk-vs-xxxxxxxxxxxxxxxxxxx\"\n",[14,75,76],{"__ignoreMap":37},[41,77,78,82,86,89],{"class":43,"line":44},[41,79,81],{"class":80},"szBVR","export",[41,83,85],{"class":84},"sVt8B"," VISIONSTORY_API_KEY",[41,87,88],{"class":80},"=",[41,90,91],{"class":51},"\"sk-vs-xxxxxxxxxxxxxxxxxxx\"\n",[32,93,97],{"className":94,"code":95,"language":96,"meta":37,"style":37},"language-python shiki shiki-themes github-light github-dark","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\n","python",[14,98,99,113,120],{"__ignoreMap":37},[41,100,101,104,107,110],{"class":43,"line":44},[41,102,103],{"class":80},"from",[41,105,106],{"class":84}," visionstory ",[41,108,109],{"class":80},"import",[41,111,112],{"class":84}," VisionStoryClient\n",[41,114,116],{"class":43,"line":115},2,[41,117,119],{"emptyLinePlaceholder":118},true,"\n",[41,121,123,126,128],{"class":43,"line":122},3,[41,124,125],{"class":84},"client ",[41,127,88],{"class":80},[41,129,130],{"class":84}," VisionStoryClient.from_env()\n",[10,132,133,134,137],{},"Keep ",[14,135,136],{},"VisionStoryClient.from_env()"," as the default, especially in shared code and agent workflows, so credentials never appear in source or chat.",[27,139,141],{"id":140},"generate-a-talking-avatar-video-in-python","Generate a talking avatar video in Python",[10,143,144,147],{},[14,145,146],{},"generate_video"," submits the job and polls until it finishes — one call in, a finished video out:",[32,149,151],{"className":94,"code":150,"language":96,"meta":37,"style":37},"from pathlib import Path\nfrom visionstory import VisionStoryClient, build_video_payload\n\nclient = VisionStoryClient.from_env()\n\npayload = build_video_payload(\n    avatar_id=\"YOUR_AVATAR_ID\",        # select from client.list_avatars()\n    text=\"Hello World, this is my first video.\",\n    voice_id=\"YOUR_VOICE_ID\",          # select from client.list_voices()\n)\nvideo = client.generate_video(payload)          # submit + poll until \"created\"\nclient.download(video[\"video_url\"], Path(\"result.mp4\"))\nprint(\"saved result.mp4\")\n",[14,152,153,165,176,180,189,194,205,224,238,255,261,275,293],{"__ignoreMap":37},[41,154,155,157,160,162],{"class":43,"line":44},[41,156,103],{"class":80},[41,158,159],{"class":84}," pathlib ",[41,161,109],{"class":80},[41,163,164],{"class":84}," Path\n",[41,166,167,169,171,173],{"class":43,"line":115},[41,168,103],{"class":80},[41,170,106],{"class":84},[41,172,109],{"class":80},[41,174,175],{"class":84}," VisionStoryClient, build_video_payload\n",[41,177,178],{"class":43,"line":122},[41,179,119],{"emptyLinePlaceholder":118},[41,181,183,185,187],{"class":43,"line":182},4,[41,184,125],{"class":84},[41,186,88],{"class":80},[41,188,130],{"class":84},[41,190,192],{"class":43,"line":191},5,[41,193,119],{"emptyLinePlaceholder":118},[41,195,197,200,202],{"class":43,"line":196},6,[41,198,199],{"class":84},"payload ",[41,201,88],{"class":80},[41,203,204],{"class":84}," build_video_payload(\n",[41,206,208,212,214,217,220],{"class":43,"line":207},7,[41,209,211],{"class":210},"s4XuR","    avatar_id",[41,213,88],{"class":80},[41,215,216],{"class":51},"\"YOUR_AVATAR_ID\"",[41,218,219],{"class":84},",        ",[41,221,223],{"class":222},"sJ8bj","# select from client.list_avatars()\n",[41,225,227,230,232,235],{"class":43,"line":226},8,[41,228,229],{"class":210},"    text",[41,231,88],{"class":80},[41,233,234],{"class":51},"\"Hello World, this is my first video.\"",[41,236,237],{"class":84},",\n",[41,239,241,244,246,249,252],{"class":43,"line":240},9,[41,242,243],{"class":210},"    voice_id",[41,245,88],{"class":80},[41,247,248],{"class":51},"\"YOUR_VOICE_ID\"",[41,250,251],{"class":84},",          ",[41,253,254],{"class":222},"# select from client.list_voices()\n",[41,256,258],{"class":43,"line":257},10,[41,259,260],{"class":84},")\n",[41,262,264,267,269,272],{"class":43,"line":263},11,[41,265,266],{"class":84},"video ",[41,268,88],{"class":80},[41,270,271],{"class":84}," client.generate_video(payload)          ",[41,273,274],{"class":222},"# submit + poll until \"created\"\n",[41,276,278,281,284,287,290],{"class":43,"line":277},12,[41,279,280],{"class":84},"client.download(video[",[41,282,283],{"class":51},"\"video_url\"",[41,285,286],{"class":84},"], Path(",[41,288,289],{"class":51},"\"result.mp4\"",[41,291,292],{"class":84},"))\n",[41,294,296,300,303,306],{"class":43,"line":295},13,[41,297,299],{"class":298},"sj4cs","print",[41,301,302],{"class":84},"(",[41,304,305],{"class":51},"\"saved result.mp4\"",[41,307,260],{"class":84},[10,309,310,313,314,317,318,317,321,324,325,328,329,332,333,332,336,332,339,342,343,346],{},[14,311,312],{},"build_video_payload"," takes ",[14,315,316],{},"text"," ",[19,319,320],{},"or",[14,322,323],{},"audio_url"," \u002F ",[14,326,327],{},"audio_file"," (exactly one), plus optional ",[14,330,331],{},"model_id",", ",[14,334,335],{},"aspect_ratio",[14,337,338],{},"resolution",[14,340,341],{},"speech_rate",", and more — it maps directly to the ",[14,344,345],{},"POST \u002Fapi\u002Fv1\u002Fvideo"," body.",[27,348,350],{"id":349},"use-the-visionstory-cli","Use the VisionStory CLI",[10,352,353,354,357,358,360],{},"A separate ",[14,355,356],{},"visionstory-cli"," package provides a ",[14,359,16],{}," command that covers the same surface — no code required:",[32,362,364],{"className":34,"code":363,"language":36,"meta":37,"style":37},"visionstory create-video --avatar-id YOUR_AVATAR_ID --text \"Hello from VisionStory.\" --voice-id YOUR_VOICE_ID --output result.mp4\n",[14,365,366],{"__ignoreMap":37},[41,367,368,370,373,376,379,382,385,388,391,394],{"class":43,"line":44},[41,369,16],{"class":47},[41,371,372],{"class":51}," create-video",[41,374,375],{"class":298}," --avatar-id",[41,377,378],{"class":51}," YOUR_AVATAR_ID",[41,380,381],{"class":298}," --text",[41,383,384],{"class":51}," \"Hello from VisionStory.\"",[41,386,387],{"class":298}," --voice-id",[41,389,390],{"class":51}," YOUR_VOICE_ID",[41,392,393],{"class":298}," --output",[41,395,396],{"class":51}," result.mp4\n",[10,398,399,400,404],{},"See the ",[64,401,403],{"href":402},"\u002Fguides\u002Fcli","CLI"," guide for every command, flag, and example.",[27,406,408],{"id":407},"list-models-avatars-voices-and-credits","List models, avatars, voices, and credits",[10,410,411],{},"Don't hardcode IDs — list them and pick at runtime:",[32,413,415],{"className":94,"code":414,"language":96,"meta":37,"style":37},"client.list_models()      # avatar render models\nclient.list_avatars()     # your avatars + public ones\nclient.list_voices()      # your voices + public ones\nclient.get_credits()      # remaining balance\n",[14,416,417,425,433,441],{"__ignoreMap":37},[41,418,419,422],{"class":43,"line":44},[41,420,421],{"class":84},"client.list_models()      ",[41,423,424],{"class":222},"# avatar render models\n",[41,426,427,430],{"class":43,"line":115},[41,428,429],{"class":84},"client.list_avatars()     ",[41,431,432],{"class":222},"# your avatars + public ones\n",[41,434,435,438],{"class":43,"line":122},[41,436,437],{"class":84},"client.list_voices()      ",[41,439,440],{"class":222},"# your voices + public ones\n",[41,442,443,446],{"class":43,"line":182},[41,444,445],{"class":84},"client.get_credits()      ",[41,447,448],{"class":222},"# remaining balance\n",[27,450,452],{"id":451},"verify-sdk-cli-and-mcp-compatibility","Verify SDK, CLI, and MCP compatibility",[32,454,456],{"className":94,"code":455,"language":96,"meta":37,"style":37},"from visionstory import get_contract_info\n\nprint(get_contract_info())\n# contract_version, SHA-256 contract_hash, and operation_count=24\n",[14,457,458,469,473,480],{"__ignoreMap":37},[41,459,460,462,464,466],{"class":43,"line":44},[41,461,103],{"class":80},[41,463,106],{"class":84},[41,465,109],{"class":80},[41,467,468],{"class":84}," get_contract_info\n",[41,470,471],{"class":43,"line":115},[41,472,119],{"emptyLinePlaceholder":118},[41,474,475,477],{"class":43,"line":122},[41,476,299],{"class":298},[41,478,479],{"class":84},"(get_contract_info())\n",[41,481,482],{"class":43,"line":182},[41,483,484],{"class":222},"# contract_version, SHA-256 contract_hash, and operation_count=24\n",[10,486,487,488,491,492,495],{},"The same fingerprint is available through ",[14,489,490],{},"visionstory contract"," and the MCP\nresource ",[14,493,494],{},"visionstory:\u002F\u002Fcontract",". Matching values mean the SDK, CLI, and MCP\nserver were built from the same OpenAPI and channel mapping.",[27,497,499],{"id":498},"create-avatars-clone-voices-and-upload-assets","Create avatars, clone voices, and upload assets",[32,501,503],{"className":94,"code":502,"language":96,"meta":37,"style":37},"client.create_avatar(image_url=\"https:\u002F\u002Fyour.site\u002Fface.jpg\")   # or image_file=Path(\"face.jpg\")\nclient.clone_voice(audio_url=\"https:\u002F\u002Fyour.site\u002Fsample.mp3\")   # or audio_file=Path(\"sample.mp3\")\nclient.upload_asset(url=\"https:\u002F\u002Fyour.site\u002Fclip.mp4\")          # or file_path=Path(\"clip.mp4\")\n",[14,504,505,524,541],{"__ignoreMap":37},[41,506,507,510,513,515,518,521],{"class":43,"line":44},[41,508,509],{"class":84},"client.create_avatar(",[41,511,512],{"class":210},"image_url",[41,514,88],{"class":80},[41,516,517],{"class":51},"\"https:\u002F\u002Fyour.site\u002Fface.jpg\"",[41,519,520],{"class":84},")   ",[41,522,523],{"class":222},"# or image_file=Path(\"face.jpg\")\n",[41,525,526,529,531,533,536,538],{"class":43,"line":115},[41,527,528],{"class":84},"client.clone_voice(",[41,530,323],{"class":210},[41,532,88],{"class":80},[41,534,535],{"class":51},"\"https:\u002F\u002Fyour.site\u002Fsample.mp3\"",[41,537,520],{"class":84},[41,539,540],{"class":222},"# or audio_file=Path(\"sample.mp3\")\n",[41,542,543,546,549,551,554,557],{"class":43,"line":122},[41,544,545],{"class":84},"client.upload_asset(",[41,547,548],{"class":210},"url",[41,550,88],{"class":80},[41,552,553],{"class":51},"\"https:\u002F\u002Fyour.site\u002Fclip.mp4\"",[41,555,556],{"class":84},")          ",[41,558,559],{"class":222},"# or file_path=Path(\"clip.mp4\")\n",[10,561,562,565,566,569,570,574],{},[14,563,564],{},"upload_asset"," returns a reusable ",[14,567,568],{},"asset_id"," you can reference from ",[64,571,573],{"href":572},"\u002Fguides\u002Fai-video","AI Video"," requests.",[27,576,578],{"id":577},"control-asynchronous-polling","Control asynchronous polling",[10,580,581],{},"Submit and poll separately when you want to show progress or do other work in between:",[32,583,585],{"className":94,"code":584,"language":96,"meta":37,"style":37},"created = client.create_video(payload)          # returns immediately with a video_id\nvideo = client.wait_for_video(created[\"video_id\"], poll_interval=5, timeout=600)\n",[14,586,587,600],{"__ignoreMap":37},[41,588,589,592,594,597],{"class":43,"line":44},[41,590,591],{"class":84},"created ",[41,593,88],{"class":80},[41,595,596],{"class":84}," client.create_video(payload)          ",[41,598,599],{"class":222},"# returns immediately with a video_id\n",[41,601,602,604,606,609,612,615,618,620,623,625,628,630,633],{"class":43,"line":115},[41,603,266],{"class":84},[41,605,88],{"class":80},[41,607,608],{"class":84}," client.wait_for_video(created[",[41,610,611],{"class":51},"\"video_id\"",[41,613,614],{"class":84},"], ",[41,616,617],{"class":210},"poll_interval",[41,619,88],{"class":80},[41,621,622],{"class":298},"5",[41,624,332],{"class":84},[41,626,627],{"class":210},"timeout",[41,629,88],{"class":80},[41,631,632],{"class":298},"600",[41,634,260],{"class":84},[10,636,637,640,641,644],{},[14,638,639],{},"generate_video(payload, wait=False)"," is equivalent to ",[14,642,643],{},"create_video",".",[27,646,648],{"id":647},"handle-sdk-errors-and-timeouts","Handle SDK errors and timeouts",[32,650,652],{"className":94,"code":651,"language":96,"meta":37,"style":37},"from visionstory import VisionStoryAPIError, VideoTimeoutError\n\ntry:\n    video = client.generate_video(payload)\nexcept VideoTimeoutError:\n    ...   # still not finished after `timeout` seconds\nexcept VisionStoryAPIError as e:\n    ...   # API returned an error, or the task failed — credits for failed tasks are refunded automatically\n",[14,653,654,665,669,677,687,695,703,716],{"__ignoreMap":37},[41,655,656,658,660,662],{"class":43,"line":44},[41,657,103],{"class":80},[41,659,106],{"class":84},[41,661,109],{"class":80},[41,663,664],{"class":84}," VisionStoryAPIError, VideoTimeoutError\n",[41,666,667],{"class":43,"line":115},[41,668,119],{"emptyLinePlaceholder":118},[41,670,671,674],{"class":43,"line":122},[41,672,673],{"class":80},"try",[41,675,676],{"class":84},":\n",[41,678,679,682,684],{"class":43,"line":182},[41,680,681],{"class":84},"    video ",[41,683,88],{"class":80},[41,685,686],{"class":84}," client.generate_video(payload)\n",[41,688,689,692],{"class":43,"line":191},[41,690,691],{"class":80},"except",[41,693,694],{"class":84}," VideoTimeoutError:\n",[41,696,697,700],{"class":43,"line":196},[41,698,699],{"class":298},"    ...",[41,701,702],{"class":222},"   # still not finished after `timeout` seconds\n",[41,704,705,707,710,713],{"class":43,"line":207},[41,706,691],{"class":80},[41,708,709],{"class":84}," VisionStoryAPIError ",[41,711,712],{"class":80},"as",[41,714,715],{"class":84}," e:\n",[41,717,718,720],{"class":43,"line":226},[41,719,699],{"class":298},[41,721,722],{"class":222},"   # API returned an error, or the task failed — credits for failed tasks are refunded automatically\n",[27,724,726],{"id":725},"related-visionstory-developer-guides","Related VisionStory developer guides",[728,729,730,738,745],"ul",{},[731,732,733,737],"li",{},[64,734,736],{"href":735},"\u002Fguides\u002Fquick-start","Quick start"," — the same flow, step by step.",[731,739,740,744],{},[64,741,743],{"href":742},"\u002Fguides\u002Ffor-agents","For agents"," — let an AI agent drive the API via the Skill or MCP server.",[731,746,747,751],{},[64,748,750],{"href":749},"\u002Freference","API reference"," — every endpoint the SDK wraps.",[753,754,755],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}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 .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 .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}",{"title":37,"searchDepth":115,"depth":115,"links":757},[758,759,760,761,762,763,764,765,766,767],{"id":29,"depth":115,"text":30},{"id":58,"depth":115,"text":59},{"id":140,"depth":115,"text":141},{"id":349,"depth":115,"text":350},{"id":407,"depth":115,"text":408},{"id":451,"depth":115,"text":452},{"id":498,"depth":115,"text":499},{"id":577,"depth":115,"text":578},{"id":647,"depth":115,"text":648},{"id":725,"depth":115,"text":726},"Install the official zero-dependency Python SDK for the VisionStory API, then authenticate, generate videos, upload assets, poll jobs, and download results.","md",{},{"title":772,"order":226},"Python SDK","\u002Fguides\u002Fsdk",{"title":5,"description":768},"guides\u002Fsdk","irTNqh9oz-aPVBQtr_YHVOE16lcUIh1TOLi-Us8yfNk","\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\">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:#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>\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\">\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>\u003Cspan style=\"color:#8B949E\"># select from client.list_avatars()\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 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>\u003Cspan style=\"color:#8B949E\"># select from client.list_voices()\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>\u003Cspan style=\"color:#8B949E\"># submit + poll until \"created\"\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>","\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\"> create-video\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --avatar-id\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> YOUR_AVATAR_ID\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --text\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"Hello from VisionStory.\"\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --voice-id\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> YOUR_VOICE_ID\u003C\u002Fspan>\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:#E6EDF3\">client.list_models()      \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># avatar render models\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client.list_avatars()     \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># your avatars + public ones\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client.list_voices()      \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># your voices + public ones\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client.get_credits()      \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># remaining balance\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\"> get_contract_info\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(get_contract_info())\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\"># contract_version, SHA-256 contract_hash, and operation_count=24\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\">client.create_avatar(\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">image_url\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fyour.site\u002Fface.jpg\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)   \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># or image_file=Path(\"face.jpg\")\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client.clone_voice(\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">audio_url\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fyour.site\u002Fsample.mp3\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)   \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># or audio_file=Path(\"sample.mp3\")\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client.upload_asset(\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">url\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fyour.site\u002Fclip.mp4\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)          \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># or file_path=Path(\"clip.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:#E6EDF3\">created \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.create_video(payload)          \u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\"># returns immediately with a video_id\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.wait_for_video(created[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"video_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">], \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">poll_interval\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">5\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">, \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">timeout\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">600\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:#FF7B72\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryAPIError, VideoTimeoutError\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">try\u003C\u002Fspan>\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:#FF7B72\">except\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VideoTimeoutError:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">    ...\u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\">   # still not finished after `timeout` seconds\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">except\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryAPIError \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">as\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> e:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">    ...\u003C\u002Fspan>\u003Cspan style=\"color:#8B949E\">   # API returned an error, or the task failed — credits for failed tasks are refunded automatically\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788166855862]