[{"data":1,"prerenderedAt":1114},["ShallowReactive",2],{"guide-\u002Fguides\u002Ffor-agents":3,"developer-code-34eaj7":1102,"developer-code-1tp71zs":1103,"developer-code-1gdh9rw":1104,"developer-code-7a8atz":1105,"developer-code-1svhdzf":1106,"developer-code-1gs3h2m":1107,"developer-code-1ex5t56":1108,"developer-code-9on7ab":1109,"developer-code-zvmysn":1110,"developer-code-2u142j":1111,"developer-code-c47igf":1112,"developer-code-1ue5dp2":1113},{"id":4,"title":5,"body":6,"description":1092,"extension":1093,"meta":1094,"navigation":1095,"path":1098,"seo":1099,"stem":1100,"__hash__":1101},"guides\u002Fguides\u002Ffor-agents.md","VisionStory API for AI Agents",{"type":7,"value":8,"toc":1075},"minimark",[9,18,23,126,129,158,181,185,192,201,212,236,239,257,268,365,375,382,389,414,417,441,445,455,524,530,533,544,548,554,640,655,679,683,698,723,740,743,784,806,854,858,861,868,874,878,881,887,909,913,966,970,1005,1009,1028,1057,1071],[10,11,12,13,17],"p",{},"AI agents can generate VisionStory videos, images, speech, avatars, and voices through MCP, the Python SDK, CLI, or machine-readable documentation. The Agent Skill covers talking-avatar generation, voice discovery, localized speech, transcription, and word alignment. Every channel uses the same REST API and ",[14,15,16],"code",{},"VISIONSTORY_API_KEY","; choose the integration that matches where your agent runs.",[19,20,22],"h2",{"id":21},"choose-an-ai-agent-integration","Choose an AI agent integration",[24,25,26,42],"table",{},[27,28,29],"thead",{},[30,31,32,36,39],"tr",{},[33,34,35],"th",{},"Channel",[33,37,38],{},"Install",[33,40,41],{},"Best when",[43,44,45,63,79,94,109],"tbody",{},[30,46,47,54,60],{},[48,49,50],"td",{},[51,52,53],"strong",{},"MCP server",[48,55,56,59],{},[14,57,58],{},"uvx visionstory-mcp"," — your client runs it, nothing to host",[48,61,62],{},"Claude Desktop, coding agents, and other local MCP clients",[30,64,65,70,76],{},[48,66,67],{},[51,68,69],{},"CLI",[48,71,72,75],{},[14,73,74],{},"curl -fsSL https:\u002F\u002Fdevelopers.visionstory.ai\u002Fcli | bash"," (latest release)",[48,77,78],{},"People and agents that want one persistent terminal command",[30,80,81,86,91],{},[48,82,83],{},[51,84,85],{},"Python SDK",[48,87,88],{},[14,89,90],{},"pip install visionstory",[48,92,93],{},"Agents that write and run Python",[30,95,96,101,106],{},[48,97,98],{},[51,99,100],{},"Agent Skill",[48,102,103],{},[14,104,105],{},"npx skills add visionstory-ai\u002Fskills --skill visionstory-api",[48,107,108],{},"Skill-compatible coding agents working with avatars, speech, or audio inside a repo",[30,110,111,120,123],{},[48,112,113],{},[51,114,115,116,119],{},"llms.txt + ",[14,117,118],{},".md"," pages",[48,121,122],{},"nothing — just fetch the URLs",[48,124,125],{},"Agents that browse the web and read docs on demand",[10,127,128],{},"Whichever channel you use, configure the key the same way — the agent reads it from an environment variable. If the variable is missing, the agent must explain how to set it locally and must never ask you to paste the key into chat:",[130,131,136],"pre",{"className":132,"code":133,"language":134,"meta":135,"style":135},"language-bash shiki shiki-themes github-light github-dark","export VISIONSTORY_API_KEY=\"sk-vs-xxxxxxxxxxxxxxxxxxx\"\n","bash","",[14,137,138],{"__ignoreMap":135},[139,140,143,147,151,154],"span",{"class":141,"line":142},"line",1,[139,144,146],{"class":145},"szBVR","export",[139,148,150],{"class":149},"sVt8B"," VISIONSTORY_API_KEY",[139,152,153],{"class":145},"=",[139,155,157],{"class":156},"sZZnC","\"sk-vs-xxxxxxxxxxxxxxxxxxx\"\n",[10,159,160,161,164,165,168,169,172,173,180],{},"Before asking an agent to submit a paid generation, run the read-only ",[14,162,163],{},"visionstory credits"," command or call the MCP ",[14,166,167],{},"get_credits"," tool. A ",[14,170,171],{},"401"," response means the local key is missing, expired, or invalid and must be replaced on the ",[174,175,179],"a",{"href":176,"rel":177},"https:\u002F\u002Fdevelopers.visionstory.ai\u002Fapi-keys",[178],"nofollow","API keys page",".",[19,182,184],{"id":183},"connect-the-visionstory-mcp-server","Connect the VisionStory MCP server",[10,186,187,188,191],{},"For most users, the recommended local setup below is enough. Your MCP client starts VisionStory on demand and receives the same ",[51,189,190],{},"28 public operations"," available through the SDK and CLI, including avatar framing, audio transcription, and alignment.",[193,194,196,197,200],"h3",{"id":195},"recommended-setup-run-with-uvx","Recommended setup — Run with ",[14,198,199],{},"uvx"," 👍",[10,202,203,204,207,208,211],{},"Install ",[14,205,206],{},"uv"," once. Skip this command if ",[14,209,210],{},"uvx --version"," already works:",[130,213,215],{"className":132,"code":214,"language":134,"meta":135,"style":135},"curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh\n",[14,216,217],{"__ignoreMap":135},[139,218,219,223,227,230,233],{"class":141,"line":142},[139,220,222],{"class":221},"sScJk","curl",[139,224,226],{"class":225},"sj4cs"," -LsSf",[139,228,229],{"class":156}," https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh",[139,231,232],{"class":145}," |",[139,234,235],{"class":221}," sh\n",[10,237,238],{},"Confirm VisionStory MCP can start:",[130,240,242],{"className":132,"code":241,"language":134,"meta":135,"style":135},"uvx --refresh visionstory-mcp --check\n",[14,243,244],{"__ignoreMap":135},[139,245,246,248,251,254],{"class":141,"line":142},[139,247,199],{"class":221},[139,249,250],{"class":225}," --refresh",[139,252,253],{"class":156}," visionstory-mcp",[139,255,256],{"class":225}," --check\n",[10,258,259,260,263,264,267],{},"When it prints ",[14,261,262],{},"✓ VisionStory MCP started successfully",", add this configuration to your MCP client. In Claude Desktop, open ",[51,265,266],{},"Settings → Developer → Edit Config",":",[130,269,273],{"className":270,"code":271,"language":272,"meta":135,"style":135},"language-json shiki shiki-themes github-light github-dark","{\n  \"mcpServers\": {\n    \"visionstory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"visionstory-mcp\"],\n      \"env\": { \"VISIONSTORY_API_KEY\": \"YOUR_LOCAL_VISIONSTORY_API_KEY\" }\n    }\n  }\n}\n","json",[14,274,275,280,289,297,312,327,347,353,359],{"__ignoreMap":135},[139,276,277],{"class":141,"line":142},[139,278,279],{"class":149},"{\n",[139,281,283,286],{"class":141,"line":282},2,[139,284,285],{"class":225},"  \"mcpServers\"",[139,287,288],{"class":149},": {\n",[139,290,292,295],{"class":141,"line":291},3,[139,293,294],{"class":225},"    \"visionstory\"",[139,296,288],{"class":149},[139,298,300,303,306,309],{"class":141,"line":299},4,[139,301,302],{"class":225},"      \"command\"",[139,304,305],{"class":149},": ",[139,307,308],{"class":156},"\"uvx\"",[139,310,311],{"class":149},",\n",[139,313,315,318,321,324],{"class":141,"line":314},5,[139,316,317],{"class":225},"      \"args\"",[139,319,320],{"class":149},": [",[139,322,323],{"class":156},"\"visionstory-mcp\"",[139,325,326],{"class":149},"],\n",[139,328,330,333,336,339,341,344],{"class":141,"line":329},6,[139,331,332],{"class":225},"      \"env\"",[139,334,335],{"class":149},": { ",[139,337,338],{"class":225},"\"VISIONSTORY_API_KEY\"",[139,340,305],{"class":149},[139,342,343],{"class":156},"\"YOUR_LOCAL_VISIONSTORY_API_KEY\"",[139,345,346],{"class":149}," }\n",[139,348,350],{"class":141,"line":349},7,[139,351,352],{"class":149},"    }\n",[139,354,356],{"class":141,"line":355},8,[139,357,358],{"class":149},"  }\n",[139,360,362],{"class":141,"line":361},9,[139,363,364],{"class":149},"}\n",[10,366,367,368,370,371,374],{},"Replace the API-key placeholder only in your local client configuration, then restart the client. Ask it to call ",[14,369,167],{}," and ",[14,372,373],{},"list_models","; the connection is ready when both succeed.",[193,376,378,379],{"id":377},"alternative-install-with-pip","Alternative — Install with ",[14,380,381],{},"pip",[10,383,384,385,388],{},"Use this only if you prefer a permanently installed ",[14,386,387],{},"visionstory-mcp"," command:",[130,390,392],{"className":132,"code":391,"language":134,"meta":135,"style":135},"python3 -m pip install --upgrade visionstory-mcp\n",[14,393,394],{"__ignoreMap":135},[139,395,396,399,402,405,408,411],{"class":141,"line":142},[139,397,398],{"class":221},"python3",[139,400,401],{"class":225}," -m",[139,403,404],{"class":156}," pip",[139,406,407],{"class":156}," install",[139,409,410],{"class":225}," --upgrade",[139,412,413],{"class":156}," visionstory-mcp\n",[10,415,416],{},"In the configuration above, replace the command and arguments with:",[130,418,420],{"className":270,"code":419,"language":272,"meta":135,"style":135},"\"command\": \"visionstory-mcp\",\n\"args\": []\n",[14,421,422,433],{"__ignoreMap":135},[139,423,424,427,429,431],{"class":141,"line":142},[139,425,426],{"class":156},"\"command\"",[139,428,305],{"class":149},[139,430,323],{"class":156},[139,432,311],{"class":149},[139,434,435,438],{"class":141,"line":282},[139,436,437],{"class":156},"\"args\"",[139,439,440],{"class":149},": []\n",[193,442,444],{"id":443},"advanced-connect-to-a-remote-mcp-endpoint","Advanced — Connect to a remote MCP endpoint",[10,446,447,448,450,451,454],{},"The local ",[14,449,58],{}," setup above remains the simplest option and continues to support files on your computer. Teams that want one centrally managed MCP service can additionally deploy the repository's stateless Streamable HTTP service and connect to its ",[14,452,453],{},"\u002Fmcp"," endpoint.",[130,456,458],{"className":270,"code":457,"language":272,"meta":135,"style":135},"{\n  \"mcpServers\": {\n    \"visionstory-remote\": {\n      \"url\": \"https:\u002F\u002FYOUR_MCP_HOST\u002Fmcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_LOCAL_VISIONSTORY_API_KEY\"\n      }\n    }\n  }\n}\n",[14,459,460,464,470,477,489,496,506,511,515,519],{"__ignoreMap":135},[139,461,462],{"class":141,"line":142},[139,463,279],{"class":149},[139,465,466,468],{"class":141,"line":282},[139,467,285],{"class":225},[139,469,288],{"class":149},[139,471,472,475],{"class":141,"line":291},[139,473,474],{"class":225},"    \"visionstory-remote\"",[139,476,288],{"class":149},[139,478,479,482,484,487],{"class":141,"line":299},[139,480,481],{"class":225},"      \"url\"",[139,483,305],{"class":149},[139,485,486],{"class":156},"\"https:\u002F\u002FYOUR_MCP_HOST\u002Fmcp\"",[139,488,311],{"class":149},[139,490,491,494],{"class":141,"line":314},[139,492,493],{"class":225},"      \"headers\"",[139,495,288],{"class":149},[139,497,498,501,503],{"class":141,"line":329},[139,499,500],{"class":225},"        \"Authorization\"",[139,502,305],{"class":149},[139,504,505],{"class":156},"\"Bearer YOUR_LOCAL_VISIONSTORY_API_KEY\"\n",[139,507,508],{"class":141,"line":349},[139,509,510],{"class":149},"      }\n",[139,512,513],{"class":141,"line":355},[139,514,352],{"class":149},[139,516,517],{"class":141,"line":361},[139,518,358],{"class":149},[139,520,522],{"class":141,"line":521},10,[139,523,364],{"class":149},[10,525,526,527,529],{},"This option is for teams operating a shared MCP service. Local files must be uploaded or available through HTTP(S); choose ",[14,528,199],{}," when the agent needs direct access to files on your computer.",[10,531,532],{},"For every setup, keep the API key local and never paste it into chat or commit it to Git. Generation tools wait for results by default, and deletion tools require explicit confirmation.",[10,534,535,536,539,540,543],{},"The local MCP server checks for a newer package when it starts and exposes ",[14,537,538],{},"visionstory:\u002F\u002Frelease"," with the installed version, latest version, feature highlights, release notes, and upgrade command. Update checks are cached and fail silently when offline. Set ",[14,541,542],{},"VISIONSTORY_UPDATE_CHECK=0"," to disable them. The remote MCP service is managed centrally and exposes the same resource, but it updates automatically; reconnect the MCP client to refresh its available tools.",[19,545,547],{"id":546},"use-the-python-sdk-from-an-agent","Use the Python SDK from an agent",[10,549,550,551,553],{},"If your agent writes and runs code, ",[14,552,90],{}," gives it a typed, zero-dependency client:",[130,555,559],{"className":556,"code":557,"language":558,"meta":135,"style":135},"language-python shiki shiki-themes github-light github-dark","from visionstory import VisionStoryClient, build_video_payload\n\nclient = VisionStoryClient.from_env()   # reads VISIONSTORY_API_KEY\nvideo = client.generate_video(build_video_payload(\n    avatar_id=\"YOUR_AVATAR_ID\", text=\"Hello from VisionStory.\", voice_id=\"YOUR_VOICE_ID\"))\n","python",[14,560,561,575,581,595,605],{"__ignoreMap":135},[139,562,563,566,569,572],{"class":141,"line":142},[139,564,565],{"class":145},"from",[139,567,568],{"class":149}," visionstory ",[139,570,571],{"class":145},"import",[139,573,574],{"class":149}," VisionStoryClient, build_video_payload\n",[139,576,577],{"class":141,"line":282},[139,578,580],{"emptyLinePlaceholder":579},true,"\n",[139,582,583,586,588,591],{"class":141,"line":291},[139,584,585],{"class":149},"client ",[139,587,153],{"class":145},[139,589,590],{"class":149}," VisionStoryClient.from_env()   ",[139,592,594],{"class":593},"sJ8bj","# reads VISIONSTORY_API_KEY\n",[139,596,597,600,602],{"class":141,"line":299},[139,598,599],{"class":149},"video ",[139,601,153],{"class":145},[139,603,604],{"class":149}," client.generate_video(build_video_payload(\n",[139,606,607,611,613,616,619,622,624,627,629,632,634,637],{"class":141,"line":314},[139,608,610],{"class":609},"s4XuR","    avatar_id",[139,612,153],{"class":145},[139,614,615],{"class":156},"\"YOUR_AVATAR_ID\"",[139,617,618],{"class":149},", ",[139,620,621],{"class":609},"text",[139,623,153],{"class":145},[139,625,626],{"class":156},"\"Hello from VisionStory.\"",[139,628,618],{"class":149},[139,630,631],{"class":609},"voice_id",[139,633,153],{"class":145},[139,635,636],{"class":156},"\"YOUR_VOICE_ID\"",[139,638,639],{"class":149},"))\n",[10,641,642,643,646,647,650,651,654],{},"Select both IDs immediately before building a request. Use ",[14,644,645],{},"client.list_avatars(is_public=True)"," for the public avatar library or omit ",[14,648,649],{},"is_public"," for owned avatars, then call ",[14,652,653],{},"client.list_voices()",". Values shown in examples are placeholders, not guaranteed resources.",[10,656,657,658,661,662,665,666,670,671,674,675,678],{},"Prefer the terminal? ",[14,659,660],{},"pip install visionstory-cli"," gives a ",[14,663,664],{},"visionstory"," ",[174,667,669],{"href":668},"\u002Fguides\u002Fcli","command-line tool",", so an agent can run ",[14,672,673],{},"visionstory create-video ..."," without writing code. See the ",[174,676,85],{"href":677},"\u002Fguides\u002Fsdk"," guide for the full client.",[19,680,682],{"id":681},"install-the-visionstory-agent-skill","Install the VisionStory Agent Skill",[10,684,685,686,694,695,267],{},"For skill-compatible coding agents (Claude Code, Codex, …), install the skill straight from GitHub. The ",[174,687,690,693],{"href":688,"rel":689},"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fskills",[178],[14,691,692],{},"skills"," CLI"," auto-detects your agent and drops the skill into ",[14,696,697],{},".agents\u002Fskills\u002F",[130,699,701],{"className":132,"code":700,"language":134,"meta":135,"style":135},"npx skills add visionstory-ai\u002Fskills --skill visionstory-api\n",[14,702,703],{"__ignoreMap":135},[139,704,705,708,711,714,717,720],{"class":141,"line":142},[139,706,707],{"class":221},"npx",[139,709,710],{"class":156}," skills",[139,712,713],{"class":156}," add",[139,715,716],{"class":156}," visionstory-ai\u002Fskills",[139,718,719],{"class":225}," --skill",[139,721,722],{"class":156}," visionstory-api\n",[10,724,725,726,729,730,733,734,739],{},"The installer may display Snyk warning ",[14,727,728],{},"W011"," because the text you ask the avatar to speak is sent to ",[14,731,732],{},"POST \u002Fapi\u002Fv1\u002Fvideo",". That network transfer is the purpose of the skill, not an undeclared dependency; review the generated security-audit link and the public ",[174,735,738],{"href":736,"rel":737},"https:\u002F\u002Fgithub.com\u002Fvisionstory-ai\u002Fskills",[178],"skill source"," before accepting it.",[10,741,742],{},"No Node? Clone the repo and copy the skill folder in yourself:",[130,744,746],{"className":132,"code":745,"language":134,"meta":135,"style":135},"git clone https:\u002F\u002Fgithub.com\u002Fvisionstory-ai\u002Fskills.git\nmkdir -p .agents\u002Fskills\ncp -r skills\u002Fvisionstory-api .agents\u002Fskills\u002F\n",[14,747,748,759,770],{"__ignoreMap":135},[139,749,750,753,756],{"class":141,"line":142},[139,751,752],{"class":221},"git",[139,754,755],{"class":156}," clone",[139,757,758],{"class":156}," https:\u002F\u002Fgithub.com\u002Fvisionstory-ai\u002Fskills.git\n",[139,760,761,764,767],{"class":141,"line":282},[139,762,763],{"class":221},"mkdir",[139,765,766],{"class":225}," -p",[139,768,769],{"class":156}," .agents\u002Fskills\n",[139,771,772,775,778,781],{"class":141,"line":291},[139,773,774],{"class":221},"cp",[139,776,777],{"class":225}," -r",[139,779,780],{"class":156}," skills\u002Fvisionstory-api",[139,782,783],{"class":156}," .agents\u002Fskills\u002F\n",[10,785,786,787,790,791,794,795,800,801,805],{},"The package contains ",[14,788,789],{},"SKILL.md"," (workflow instructions the agent follows) and ",[14,792,793],{},"scripts\u002Fvisionstory_api.py",", a zero-dependency Python helper for resource discovery, avatar framing, talking-avatar generation, localized text to speech, audio transcription, word alignment, polling, and downloads. Use MCP, the standalone CLI, or the Python SDK when the agent needs the complete set of 28 public operations, including AI Video, image generation, and reusable assets. Skills-compatible agents pick it up automatically; you can also ",[174,796,799],{"href":797,"rel":798},"https:\u002F\u002Fdevelopers.visionstory.ai\u002Fskills\u002Fvisionstory-api\u002FSKILL.md",[178],"view the developer-site SKILL.md"," without downloading, or use the public distribution mirror at ",[174,802,804],{"href":736,"rel":803},[178],"github.com\u002Fvisionstory-ai\u002Fskills",". The helper works standalone too:",[130,807,809],{"className":132,"code":808,"language":134,"meta":135,"style":135},"python3 .agents\u002Fskills\u002Fvisionstory-api\u002Fscripts\u002Fvisionstory_api.py models\npython3 .agents\u002Fskills\u002Fvisionstory-api\u002Fscripts\u002Fvisionstory_api.py create-video --avatar-id YOUR_AVATAR_ID --text \"Hello from VisionStory.\" --voice-id YOUR_VOICE_ID --output result.mp4\n",[14,810,811,821],{"__ignoreMap":135},[139,812,813,815,818],{"class":141,"line":142},[139,814,398],{"class":221},[139,816,817],{"class":156}," .agents\u002Fskills\u002Fvisionstory-api\u002Fscripts\u002Fvisionstory_api.py",[139,819,820],{"class":156}," models\n",[139,822,823,825,827,830,833,836,839,842,845,848,851],{"class":141,"line":282},[139,824,398],{"class":221},[139,826,817],{"class":156},[139,828,829],{"class":156}," create-video",[139,831,832],{"class":225}," --avatar-id",[139,834,835],{"class":156}," YOUR_AVATAR_ID",[139,837,838],{"class":225}," --text",[139,840,841],{"class":156}," \"Hello from VisionStory.\"",[139,843,844],{"class":225}," --voice-id",[139,846,847],{"class":156}," YOUR_VOICE_ID",[139,849,850],{"class":225}," --output",[139,852,853],{"class":156}," result.mp4\n",[19,855,857],{"id":856},"give-agents-llmstxt-and-openapi","Give agents llms.txt and OpenAPI",[10,859,860],{},"Point any web-capable agent at the docs index; it links every guide in agent-readable form:",[130,862,866],{"className":863,"code":865,"language":621,"meta":135},[864],"language-text","Read https:\u002F\u002Fdevelopers.visionstory.ai\u002Fllms.txt for the VisionStory API docs index.\nAppend .md to any guide URL to get that guide as Markdown.\nLoad the one guide that matches the task, then use OpenAPI for exact fields.\nUse https:\u002F\u002Fdevelopers.visionstory.ai\u002Fllms-full.txt only when the task spans several capabilities.\nUse https:\u002F\u002Fdevelopers.visionstory.ai\u002Fopenapi.json for the complete machine-readable API contract.\n",[14,867,865],{"__ignoreMap":135},[10,869,870,871,873],{},"You can also hand a single ",[14,872,118],{}," guide URL or the OpenAPI JSON URL to an agent directly.",[19,875,877],{"id":876},"generate-a-video-with-one-agent-instruction","Generate a video with one agent instruction",[10,879,880],{},"With the Skill installed (or the MCP server connected), a single instruction produces a video:",[882,883,884],"blockquote",{},[10,885,886],{},"Create a talking-avatar video that says \"Welcome to our launch week!\", pick a friendly public avatar and an energetic voice, wait for it to finish, and save it as launch.mp4.",[10,888,889,890,892,893,896,897,900,901,904,905,180],{},"The agent will list avatars and voices, submit ",[14,891,732],{},", poll ",[14,894,895],{},"GET \u002Fapi\u002Fv1\u002Fvideo?video_id=..."," until ",[14,898,899],{},"created",", and download the ",[14,902,903],{},"video_url"," — the same flow as the ",[174,906,908],{"href":907},"\u002Fguides\u002Fquick-start","Quick start",[19,910,912],{"id":911},"security-and-reliability-rules-for-agents","Security and reliability rules for agents",[914,915,916,923,926,939,942,949,952,959],"ul",{},[917,918,919,920,922],"li",{},"Read the key from ",[14,921,16],{},"; never print, log, or commit it.",[917,924,925],{},"If the key is missing, explain how the user can set it locally; never ask them to paste it into chat.",[917,927,928,929,618,932,618,935,938],{},"Discover resources (",[14,930,931],{},"GET \u002Fapi\u002Fv1\u002Fmodels",[14,933,934],{},"\u002Fapi\u002Fv1\u002Favatars",[14,936,937],{},"\u002Fapi\u002Fv1\u002Fvoices",") instead of guessing IDs.",[917,940,941],{},"Treat every ID shown in documentation as a placeholder until it has been returned by a discovery or creation request.",[917,943,944,945,948],{},"Pass ",[14,946,947],{},"client_request_id"," when the create operation supports it so network retries cannot create a second charged task.",[917,950,951],{},"Poll no faster than every 5 seconds; stop after 10 minutes unless asked to keep waiting.",[917,953,954,955,958],{},"Handle the ",[14,956,957],{},"failed"," status explicitly and report the server's error message (with credentials redacted).",[917,960,961,962,965],{},"Never call a ",[14,963,964],{},"DELETE"," operation without an explicit user request and confirmation immediately before the call.",[19,967,969],{"id":968},"related-visionstory-developer-guides","Related VisionStory developer guides",[914,971,972,977,984,991,998],{},[917,973,974,976],{},[174,975,908],{"href":907}," — the underlying five-step flow.",[917,978,979,983],{},[174,980,982],{"href":981},"\u002Fguides\u002Fai-video","AI Video"," — text-to-video and image-to-video for agents using an active Pro API key.",[917,985,986,990],{},[174,987,989],{"href":988},"\u002Fguides\u002Faudio-understanding","Audio Transcription and Alignment"," — speech-to-text, SRT, speaker labels, and word timing.",[917,992,993,997],{},[174,994,996],{"href":995},"\u002Freference","API reference"," — every endpoint the channels are built on.",[917,999,1000,1004],{},[174,1001,1003],{"href":1002},"\u002Fguides\u002Fchangelog","Changelog"," — documentation version, API changes, and deprecation status.",[19,1006,1008],{"id":1007},"structured-media-understanding","Structured media understanding",[10,1010,1011,1012,1015,1016,1019,1020,1023,1024,1027],{},"Use ",[14,1013,1014],{},"understand_media(prompt, inputs, schema)"," for structured extraction from 1–8 images, audio clips, or videos. The prompt must contain 1–5000 characters and the JSON Schema must describe a top-level object. The synchronous call allows 180 seconds and returns ",[14,1017,1018],{},"output",", token ",[14,1021,1022],{},"usage",", and ",[14,1025,1026],{},"cost_credit","; there is no model selector or free-text mode. Successful calls are charged, so do not automatically repeat timeouts.",[10,1029,1030,1031,1034,1035,1038,1039,1042,1043,618,1046,618,1049,1052,1053,1056],{},"Remote MCP accepts media URLs or asset IDs; local MCP additionally accepts ",[14,1032,1033],{},"inline_data",". The Agent Skill helper exposes ",[14,1036,1037],{},"understand-media --prompt ... --inputs ... --schema ...",". Both MCP variants also accept optional ",[14,1040,1041],{},"speech_rate"," (",[14,1044,1045],{},"slow",[14,1047,1048],{},"normal",[14,1050,1051],{},"fast",") on ",[14,1054,1055],{},"create_speech","; omission or null uses normal speed.",[10,1058,1059,1060,370,1065,1070],{},"See ",[174,1061,1064],{"href":1062,"rel":1063},"https:\u002F\u002Fdevelopers.visionstory.ai\u002Fguides\u002Fmedia-understanding",[178],"Media Understanding",[174,1066,1069],{"href":1067,"rel":1068},"https:\u002F\u002Fdevelopers.visionstory.ai\u002Fguides\u002Ftext-to-speech",[178],"Text to Speech"," for complete contracts.",[1072,1073,1074],"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":135,"searchDepth":282,"depth":282,"links":1076},[1077,1078,1085,1086,1087,1088,1089,1090,1091],{"id":21,"depth":282,"text":22},{"id":183,"depth":282,"text":184,"children":1079},[1080,1082,1084],{"id":195,"depth":291,"text":1081},"Recommended setup — Run with uvx 👍",{"id":377,"depth":291,"text":1083},"Alternative — Install with pip",{"id":443,"depth":291,"text":444},{"id":546,"depth":282,"text":547},{"id":681,"depth":282,"text":682},{"id":856,"depth":282,"text":857},{"id":876,"depth":282,"text":877},{"id":911,"depth":282,"text":912},{"id":968,"depth":282,"text":969},{"id":1007,"depth":282,"text":1008},"Connect AI agents to VisionStory with MCP, the Agent Skill, Python SDK, CLI, llms.txt, and OpenAPI for secure, automated media generation.","md",{},{"title":1096,"order":1097},"For agents",11,"\u002Fguides\u002Ffor-agents",{"title":5,"description":1092},"guides\u002Ffor-agents","vRxoZ3B0crtlsAIe1mGknu6jgmI0JS0BDv_-rwhjoeE","\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\">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>Read https:\u002F\u002Fdevelopers.visionstory.ai\u002Fllms.txt for the VisionStory API docs index.\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>Append .md to any guide URL to get that guide as Markdown.\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>Load the one guide that matches the task, then use OpenAPI for exact fields.\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>Use https:\u002F\u002Fdevelopers.visionstory.ai\u002Fllms-full.txt only when the task spans several capabilities.\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>Use https:\u002F\u002Fdevelopers.visionstory.ai\u002Fopenapi.json for the complete machine-readable API contract.\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:#FFA657\">curl\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -LsSf\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\"> |\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\"> sh\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\">uvx\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --refresh\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> visionstory-mcp\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --check\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\">  \"mcpServers\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"visionstory\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"command\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"uvx\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"args\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: [\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"visionstory-mcp\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">],\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"env\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: { \u003C\u002Fspan>\u003Cspan style=\"color:#7EE787\">\"VISIONSTORY_API_KEY\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"YOUR_LOCAL_VISIONSTORY_API_KEY\"\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\">  }\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\">python3\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -m\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> pip\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> install\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> --upgrade\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> visionstory-mcp\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:#A5D6FF\">\"command\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"visionstory-mcp\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">\"args\"\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:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"mcpServers\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"visionstory-remote\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002FYOUR_MCP_HOST\u002Fmcp\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">      \"headers\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">        \"Authorization\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Bearer YOUR_LOCAL_VISIONSTORY_API_KEY\"\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\">\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:#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>\u003Cspan style=\"color:#8B949E\"># reads VISIONSTORY_API_KEY\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(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:#FFA657\">text\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Hello from VisionStory.\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">, \u003C\u002Fspan>\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\">\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\">git\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> clone\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> https:\u002F\u002Fgithub.com\u002Fvisionstory-ai\u002Fskills.git\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">mkdir\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -p\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> .agents\u002Fskills\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">cp\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> -r\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> skills\u002Fvisionstory-api\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> .agents\u002Fskills\u002F\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\"> models\u003C\u002Fspan>\u003C\u002Fspan>\n\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:#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>",1790231923842]