[{"data":1,"prerenderedAt":999},["ShallowReactive",2],{"guide-\u002Fguides-zh\u002Fquick-start":3,"developer-code-eb0qrl":985,"developer-code-34eaj7":986,"developer-code-1w80f9x":987,"developer-code-1wjk1yk":988,"developer-code-1obeumo":989,"developer-code-1ag7cua":990,"developer-code-14f04zz":991,"developer-code-1tp71zs":992,"developer-code-1xdn30c":993,"developer-code-yoowr8":994,"developer-code-1xbw2pz":995,"developer-code-1sctawa":996,"developer-code-1m51tx2":997,"developer-code-1cqt0k1":998},{"id":4,"title":5,"body":6,"description":976,"extension":977,"meta":978,"navigation":979,"path":981,"seo":982,"stem":983,"__hash__":984},"guidesZh\u002Fguides-zh\u002Fquick-start.md","数字人视频 API 快速开始",{"type":7,"value":8,"toc":962},"minimark",[9,13,18,34,45,48,75,82,85,121,137,141,148,222,226,229,245,287,290,293,314,317,347,354,357,364,389,392,450,453,462,466,473,589,630,653,657,660,690,747,750,754,767,788,792,795,929,933,958],[10,11,12],"p",{},"本指南用五个步骤完成一个数字人视频：配置 VisionStory API 认证、提交文本脚本、轮询异步任务，并将生成的 MP4 保存到本地。",[14,15,17],"h2",{"id":16},"_1-create-a-visionstory-api-key","1. 创建 VisionStory API Key",[10,19,20,21,28,29,33],{},"注册后，在 ",[22,23,27],"a",{"href":24,"rel":25},"https:\u002F\u002Fdevelopers.visionstory.ai\u002Fapi-keys",[26],"nofollow","VisionStory API Key 页面","创建密钥。每次请求都通过 ",[30,31,32],"code",{},"X-API-Key"," 请求头传入：",[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],{},"密钥应保存在服务端，不要暴露在浏览器代码或公开仓库中。以下示例从环境变量读取密钥：",[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 时，也可以在安装后运行 ",[30,79,80],{},"visionstory login","。它会隐藏输入并验证密钥，\n然后保存供后续 CLI 会话使用，不会将密钥写入 Shell 历史记录。",[10,83,84],{},"开始付费生成前，先通过只读请求验证密钥：",[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],{},"成功响应包含订阅方案和剩余点数；",[30,125,126],{},"remaining"," 是当前 VisionStory 点数余额。\n返回 ",[30,129,130],{},"401"," 表示密钥缺失、过期或已失效。请先前往\n",[22,133,135],{"href":24,"rel":134},[26],"API Key 页面","创建或更换密钥，再继续。",[14,138,140],{"id":139},"_2-choose-an-api-client","2. 选择 API 客户端",[10,142,143,144,147],{},"按任务选择接入方式即可，之后可以随时切换，因为所有接入方式都使用同一个 VisionStory API 和 ",[30,145,146],{},"VISIONSTORY_API_KEY","。",[149,150,151,164],"table",{},[152,153,154],"thead",{},[155,156,157,161],"tr",{},[158,159,160],"th",{},"目标",[158,162,163],{},"推荐方式",[165,166,167,179,189,202,212],"tbody",{},[155,168,169,173],{},[170,171,172],"td",{},"将 VisionStory 接入 Python 应用",[170,174,175],{},[176,177,178],"strong",{},"Python SDK",[155,180,181,184],{},[170,182,183],{},"执行临时命令、Shell 脚本或 CI 任务",[170,185,186],{},[176,187,188],{},"VisionStory CLI",[155,190,191,194],{},[170,192,193],{},"让 AI Agent 将完整 API 作为工具使用",[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],{},"为编码 Agent 提供专注于数字人视频的工作流",[170,208,209],{},[176,210,211],{},"Agent Skill",[155,213,214,217],{},[170,215,216],{},"使用其他后端语言接入",[170,218,219],{},[176,220,221],{},"REST API",[223,224,178],"h3",{"id":225},"python-sdk",[10,227,228],{},"安装带类型定义、无运行时依赖的 Python 客户端：",[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],{},"在隔离环境中安装 CLI，或升级到最新版本：",[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],{},"如有提示，先重启终端，再验证认证并查询有效的资源 ID：",[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,147],{},"完整命令见 ",[22,351,353],{"href":352},"\u002Fguides\u002Fcli","CLI 指南",[223,355,211],{"id":356},"agent-skill",[10,358,359,360,363],{},"面向数字人视频的 Agent Skill 包含 ",[30,361,362],{},"SKILL.md"," 和无依赖的 Python 辅助程序，可处理认证、Base64 编码、轮询和下载。安装时会自动检测支持的编码 Agent：",[35,365,367],{"className":50,"code":366,"language":52,"meta":42,"style":42},"npx skills add visionstory-ai\u002Fskills --skill visionstory-api\n",[30,368,369],{"__ignoreMap":42},[56,370,371,374,377,380,383,386],{"class":58,"line":59},[56,372,373],{"class":94},"npx",[56,375,376],{"class":73}," skills",[56,378,379],{"class":73}," add",[56,381,382],{"class":73}," visionstory-ai\u002Fskills",[56,384,385],{"class":98}," --skill",[56,387,388],{"class":73}," visionstory-api\n",[10,390,391],{},"然后用一条命令创建视频：",[35,393,395],{"className":50,"code":394,"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,396,397,410,420,430,441],{"__ignoreMap":42},[56,398,399,402,405,408],{"class":58,"line":59},[56,400,401],{"class":94},"python3",[56,403,404],{"class":73}," .agents\u002Fskills\u002Fvisionstory-api\u002Fscripts\u002Fvisionstory_api.py",[56,406,407],{"class":73}," create-video",[56,409,114],{"class":98},[56,411,412,415,418],{"class":58,"line":117},[56,413,414],{"class":98},"  --avatar-id",[56,416,417],{"class":73}," YOUR_AVATAR_ID",[56,419,114],{"class":98},[56,421,422,425,428],{"class":58,"line":274},[56,423,424],{"class":98},"  --text",[56,426,427],{"class":73}," \"Hello from VisionStory.\"",[56,429,114],{"class":98},[56,431,433,436,439],{"class":58,"line":432},4,[56,434,435],{"class":98},"  --voice-id",[56,437,438],{"class":73}," YOUR_VOICE_ID",[56,440,114],{"class":98},[56,442,444,447],{"class":58,"line":443},5,[56,445,446],{"class":98},"  --output",[56,448,449],{"class":73}," result.mp4\n",[223,451,221],{"id":452},"rest-api",[10,454,455,456,458,459,147],{},"使用 ",[30,457,95],{}," 或任意 HTTP 客户端直接调用 API。本指南末尾的完整 Python 示例仅需 ",[30,460,461],{},"requests",[14,463,465],{"id":464},"_3-generate-a-talking-avatar-video","3. 生成数字人视频",[10,467,468,469,472],{},"使用公共形象和声音提交文本脚本。请求会立即返回 ",[30,470,471],{},"video_id","，生成过程在后台异步继续：",[35,474,476],{"className":50,"code":475,"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,477,478,486,499,508,516,521,527,533,539,545,551,557,563,569,575,583],{"__ignoreMap":42},[56,479,480,482,484],{"class":58,"line":59},[56,481,95],{"class":94},[56,483,99],{"class":98},[56,485,114],{"class":98},[56,487,488,491,493,495,497],{"class":58,"line":117},[56,489,490],{"class":98},"  -H",[56,492,105],{"class":73},[56,494,108],{"class":66},[56,496,111],{"class":73},[56,498,114],{"class":98},[56,500,501,503,506],{"class":58,"line":274},[56,502,490],{"class":98},[56,504,505],{"class":73}," \"Content-Type: application\u002Fjson\"",[56,507,114],{"class":98},[56,509,510,513],{"class":58,"line":432},[56,511,512],{"class":98},"  -d",[56,514,515],{"class":73}," '{\n",[56,517,518],{"class":58,"line":443},[56,519,520],{"class":73},"    \"model_id\": \"vs_character_v4\",\n",[56,522,524],{"class":58,"line":523},6,[56,525,526],{"class":73},"    \"avatar_id\": \"YOUR_AVATAR_ID\",\n",[56,528,530],{"class":58,"line":529},7,[56,531,532],{"class":73},"    \"client_request_id\": \"YOUR_UNIQUE_REQUEST_ID\",\n",[56,534,536],{"class":58,"line":535},8,[56,537,538],{"class":73},"    \"text_script\": {\n",[56,540,542],{"class":58,"line":541},9,[56,543,544],{"class":73},"      \"text\": \"Hello World, this is my first test video.\",\n",[56,546,548],{"class":58,"line":547},10,[56,549,550],{"class":73},"      \"voice_id\": \"YOUR_VOICE_ID\",\n",[56,552,554],{"class":58,"line":553},11,[56,555,556],{"class":73},"      \"speech_rate\": \"normal\"\n",[56,558,560],{"class":58,"line":559},12,[56,561,562],{"class":73},"    },\n",[56,564,566],{"class":58,"line":565},13,[56,567,568],{"class":73},"    \"aspect_ratio\": \"9:16\",\n",[56,570,572],{"class":58,"line":571},14,[56,573,574],{"class":73},"    \"resolution\": \"720p\"\n",[56,576,578,581],{"class":58,"line":577},15,[56,579,580],{"class":73},"  }'",[56,582,114],{"class":98},[56,584,586],{"class":58,"line":585},16,[56,587,588],{"class":73},"  https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo\n",[35,590,594],{"className":591,"code":592,"language":593,"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,595,596,601,609,620,625],{"__ignoreMap":42},[56,597,598],{"class":58,"line":59},[56,599,600],{"class":66},"{\n",[56,602,603,606],{"class":58,"line":117},[56,604,605],{"class":98},"  \"data\"",[56,607,608],{"class":66},": {\n",[56,610,611,614,617],{"class":58,"line":274},[56,612,613],{"class":98},"    \"video_id\"",[56,615,616],{"class":66},": ",[56,618,619],{"class":73},"\"YOUR_VIDEO_ID\"\n",[56,621,622],{"class":58,"line":432},[56,623,624],{"class":66},"  }\n",[56,626,627],{"class":58,"line":443},[56,628,629],{"class":66},"}\n",[10,631,632,633,636,637,640,641,644,645,648,649,652],{},"正式接入前，请通过 ",[30,634,635],{},"GET \u002Fapi\u002Fv1\u002Fmodels","、",[30,638,639],{},"GET \u002Fapi\u002Fv1\u002Favatars"," 和 ",[30,642,643],{},"GET \u002Fapi\u002Fv1\u002Fvoices"," 查询当前有效 ID，不要写死。要使用自己的音频，请用 ",[30,646,647],{},"audio_script"," 替代 ",[30,650,651],{},"text_script","，两者不能同时传入。",[14,654,656],{"id":655},"_4-poll-the-video-generation-job","4. 轮询视频任务",[10,658,659],{},"每 5 秒查询一次任务，直到进入最终状态：",[35,661,663],{"className":50,"code":662,"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,664,665,673,685],{"__ignoreMap":42},[56,666,667,669,671],{"class":58,"line":59},[56,668,95],{"class":94},[56,670,99],{"class":98},[56,672,114],{"class":98},[56,674,675,677,679,681,683],{"class":58,"line":117},[56,676,490],{"class":98},[56,678,105],{"class":73},[56,680,108],{"class":66},[56,682,111],{"class":73},[56,684,114],{"class":98},[56,686,687],{"class":58,"line":274},[56,688,689],{"class":73},"  \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo?video_id=YOUR_VIDEO_ID\"\n",[149,691,692,702],{},[152,693,694],{},[155,695,696,699],{},[158,697,698],{},"status",[158,700,701],{},"含义",[165,703,704,714,724,737],{},[155,705,706,711],{},[170,707,708],{},[30,709,710],{},"queued",[170,712,713],{},"已接收，等待处理",[155,715,716,721],{},[170,717,718],{},[30,719,720],{},"creating",[170,722,723],{},"生成中",[155,725,726,731],{},[170,727,728],{},[30,729,730],{},"created",[170,732,733,734],{},"已完成，可以使用 ",[30,735,736],{},"video_url",[155,738,739,744],{},[170,740,741],{},[30,742,743],{},"failed",[170,745,746],{},"生成失败，停止轮询并检查错误",[10,748,749],{},"轮询间隔不要短于 5 秒，等待约 10 分钟后应停止。",[14,751,753],{"id":752},"_5-download-the-generated-mp4","5. 下载生成的 MP4",[10,755,756,757,759,760,762,763,766],{},"状态为 ",[30,758,730],{}," 时，响应包含 ",[30,761,736],{},"。已完成的视频保留 ",[176,764,765],{},"7 天","；如需永久保存，请下载文件：",[35,768,770],{"className":50,"code":769,"language":52,"meta":42,"style":42},"curl -sL -o result.mp4 \"\u003Cvideo_url from the response>\"\n",[30,771,772],{"__ignoreMap":42},[56,773,774,776,779,782,785],{"class":58,"line":59},[56,775,95],{"class":94},[56,777,778],{"class":98}," -sL",[56,780,781],{"class":98}," -o",[56,783,784],{"class":73}," result.mp4",[56,786,787],{"class":73}," \"\u003Cvideo_url from the response>\"\n",[14,789,791],{"id":790},"complete-python-sdk-example","完整 Python SDK 示例",[10,793,794],{},"使用 SDK，只需几行代码即可完成整个流程：",[35,796,798],{"className":247,"code":797,"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,799,800,812,823,827,836,846,860,872,884,889,899,916],{"__ignoreMap":42},[56,801,802,804,807,809],{"class":58,"line":59},[56,803,256],{"class":62},[56,805,806],{"class":66}," pathlib ",[56,808,262],{"class":62},[56,810,811],{"class":66}," Path\n",[56,813,814,816,818,820],{"class":58,"line":117},[56,815,256],{"class":62},[56,817,259],{"class":66},[56,819,262],{"class":62},[56,821,822],{"class":66}," VisionStoryClient, build_video_payload\n",[56,824,825],{"class":58,"line":274},[56,826,271],{"emptyLinePlaceholder":270},[56,828,829,831,833],{"class":58,"line":432},[56,830,277],{"class":66},[56,832,70],{"class":62},[56,834,835],{"class":66}," VisionStoryClient.from_env()\n",[56,837,838,841,843],{"class":58,"line":443},[56,839,840],{"class":66},"payload ",[56,842,70],{"class":62},[56,844,845],{"class":66}," build_video_payload(\n",[56,847,848,852,854,857],{"class":58,"line":523},[56,849,851],{"class":850},"s4XuR","    avatar_id",[56,853,70],{"class":62},[56,855,856],{"class":73},"\"YOUR_AVATAR_ID\"",[56,858,859],{"class":66},",\n",[56,861,862,865,867,870],{"class":58,"line":529},[56,863,864],{"class":850},"    text",[56,866,70],{"class":62},[56,868,869],{"class":73},"\"Hello World, this is my first test video.\"",[56,871,859],{"class":66},[56,873,874,877,879,882],{"class":58,"line":535},[56,875,876],{"class":850},"    voice_id",[56,878,70],{"class":62},[56,880,881],{"class":73},"\"YOUR_VOICE_ID\"",[56,883,859],{"class":66},[56,885,886],{"class":58,"line":541},[56,887,888],{"class":66},")\n",[56,890,891,894,896],{"class":58,"line":547},[56,892,893],{"class":66},"video ",[56,895,70],{"class":62},[56,897,898],{"class":66}," client.generate_video(payload)\n",[56,900,901,904,907,910,913],{"class":58,"line":553},[56,902,903],{"class":66},"client.download(video[",[56,905,906],{"class":73},"\"video_url\"",[56,908,909],{"class":66},"], Path(",[56,911,912],{"class":73},"\"result.mp4\"",[56,914,915],{"class":66},"))\n",[56,917,918,921,924,927],{"class":58,"line":559},[56,919,920],{"class":98},"print",[56,922,923],{"class":66},"(",[56,925,926],{"class":73},"\"saved result.mp4\"",[56,928,888],{"class":66},[14,930,932],{"id":931},"related-visionstory-api-guides","相关 VisionStory API 指南",[934,935,936,944,951],"ul",{},[937,938,939,943],"li",{},[22,940,942],{"href":941},"\u002Fguides\u002Foverview","阅读概览","，了解核心资源、响应结构和模型选择。",[937,945,946,950],{},[22,947,949],{"href":948},"\u002Freference","浏览 API 参考","，查看请求结构、参数和响应。",[937,952,953,954,147],{},"准备执行真实请求时，先",[22,955,957],{"href":24,"rel":956},[26],"获取 API Key",[959,960,961],"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":963},[964,965,971,972,973,974,975],{"id":16,"depth":117,"text":17},{"id":139,"depth":117,"text":140,"children":966},[967,968,969,970],{"id":225,"depth":274,"text":178},{"id":289,"depth":274,"text":188},{"id":356,"depth":274,"text":211},{"id":452,"depth":274,"text":221},{"id":464,"depth":117,"text":465},{"id":655,"depth":117,"text":656},{"id":752,"depth":117,"text":753},{"id":790,"depth":117,"text":791},{"id":931,"depth":117,"text":932},"使用 VisionStory REST API 或 Python SDK 生成并下载第一个数字人视频，完成认证、异步任务轮询和本地保存。","md",{},{"title":980,"order":117},"快速开始","\u002Fguides-zh\u002Fquick-start",{"title":5,"description":976},"guides-zh\u002Fquick-start","niVOEo280Hln-bhlNtjbvACcjEwH0B_EbzNyWO40vmQ","\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]