[{"data":1,"prerenderedAt":216},["ShallowReactive",2],{"reference-detail-en-create_video_api_v1_video_post":3,"developer-code-1gcr9az":214,"developer-code-4ockr0":215},{"tag":4,"sourceTag":5,"tagSlug":6,"method":7,"path":8,"slug":9,"summary":10,"description":11,"operationId":12,"groupOrder":13,"descriptionHtml":14,"parameters":15,"requestBody":23,"responses":135,"security":201,"codeSamples":204},"Talking Avatar Video","Videos","videos","POST","\u002Fapi\u002Fv1\u002Fvideo","create-video","Generate video","Generate a talking-avatar video: an avatar speaks a script provided either as text-to-speech\n(`text_script`) or pre-recorded audio (`audio_script`). Generation is asynchronous — poll\nGET \u002Fapi\u002Fv1\u002Fvideo for status. Finished videos are retained for 7 days, so download promptly.\n\nPass `client_request_id` to make retries idempotent (no double charge).","create_video_api_v1_video_post",10,"\u003Cp>Generate a talking-avatar video: an avatar speaks a script provided either as text-to-speech (\u003Ccode>text_script\u003C\u002Fcode>) or pre-recorded audio (\u003Ccode>audio_script\u003C\u002Fcode>). Generation is asynchronous — poll GET \u002Fapi\u002Fv1\u002Fvideo for status. Finished videos are retained for 7 days, so download promptly.\u003C\u002Fp>\u003Cp>Pass \u003Ccode>client_request_id\u003C\u002Fcode> to make retries idempotent (no double charge).\u003C\u002Fp>",[16],{"name":17,"in":18,"required":19,"description":20,"type":21,"example":22},"X-API-Key","header",true,"Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](\u002Fapi-keys) (Pro plan and up).","string","sk-vs-your-api-key",{"required":19,"contentType":24,"schema":25,"example":129},"application\u002Fjson",{"type":26,"description":27,"nullable":28,"properties":29},"CreateVideoRequest","",false,[30,38,74,78,82,86,96,101,109],{"name":31,"required":28,"type":21,"description":32,"nullable":28,"enum":33,"default":34,"properties":37},"aspect_ratio","Output aspect ratio for the rendered video; defaults to `9:16`.",[34,35,36],"9:16","16:9","1:1",[],{"name":39,"required":28,"type":40,"description":41,"nullable":19,"properties":42},"audio_script","AudioScript | null","Pre-recorded narration audio to drive the avatar. Provide either `audio_script` or `text_script`.",[43,48,53,66,70],{"name":44,"required":28,"type":45,"description":46,"nullable":19,"properties":47},"audio_url","string | null","Publicly reachable URL of narration audio to drive the avatar. Provide either this or `inline_data`.",[],{"name":49,"required":28,"type":50,"description":51,"nullable":28,"default":28,"properties":52},"denoise","boolean","If true, apply noise reduction to the uploaded audio before generation.",[],{"name":54,"required":28,"type":55,"description":56,"nullable":19,"properties":57},"inline_data","InlineDataModel | null","Narration audio as inline base64 data. Provide either this or `audio_url`.",[58,62],{"name":59,"required":19,"type":21,"description":60,"nullable":28,"properties":61},"data","The file's raw bytes encoded as a base64 string (no `data:` URI prefix).",[],{"name":63,"required":19,"type":21,"description":64,"nullable":28,"properties":65},"mime_type","MIME type of the inline data; the gateway uses it to tell image \u002F audio \u002F video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav'] and images ['image\u002Fjpeg', 'image\u002Fjpg', 'image\u002Fpng', 'image\u002Fwebp', 'image\u002Fheic'].",[],{"name":67,"required":28,"type":50,"description":68,"nullable":28,"default":28,"properties":69},"voice_change","If true, re-synthesize the uploaded audio with the voice in `voice_id` (voice conversion) while keeping the original timing.",[],{"name":71,"required":28,"type":45,"description":72,"nullable":19,"properties":73},"voice_id","Target voice for conversion when `voice_change` is true. Use an id from GET \u002Fapi\u002Fv1\u002Fvoices.",[],{"name":75,"required":19,"type":21,"description":76,"nullable":28,"properties":77},"avatar_id","Avatar that speaks the script. Use an id from GET \u002Fapi\u002Fv1\u002Favatars (public or your own).",[],{"name":79,"required":28,"type":21,"description":80,"nullable":28,"default":27,"properties":81},"background_color","Optional solid background as a 6-digit hex color, e.g. `#00b140`. Leave empty to keep the avatar's original background; setting it renders the avatar on this color (chroma-key friendly).",[],{"name":83,"required":28,"type":45,"description":84,"nullable":19,"properties":85},"client_request_id","Optional idempotency key. Resubmitting with the same value within 24h returns the original task instead of creating (and charging) a new one. Safe for retries.",[],{"name":87,"required":28,"type":21,"description":88,"nullable":28,"enum":89,"default":90,"properties":95},"emotion","Expressive tone the avatar performs; defaults to `cheerful`.",[90,91,92,93,94],"cheerful","angry","marketing","news","singing",[],{"name":97,"required":28,"type":21,"description":98,"nullable":28,"default":99,"properties":100},"model_id","Rendering model to use; see GET \u002Fapi\u002Fv1\u002Fmodels. Defaults to `vs_character_v4`.","vs_character_v4",[],{"name":102,"required":28,"type":21,"description":103,"nullable":28,"enum":104,"default":105,"properties":108},"resolution","Output resolution: `720p`, `1080p`, or `2k`. Higher values cost more credits and take longer to render; defaults to `720p`.",[105,106,107],"720p","1080p","2k",[],{"name":110,"required":28,"type":111,"description":112,"nullable":19,"properties":113},"text_script","TextScript | null","Text-to-speech script (text + voice). Provide either `text_script` or `audio_script`.",[114,122,126],{"name":115,"required":28,"type":45,"description":116,"nullable":19,"enum":117,"default":119,"properties":121},"speech_rate","Speaking speed of the synthesized voice; defaults to `normal`.",[118,119,120],"slow","normal","fast",[],{"name":123,"required":19,"type":21,"description":124,"nullable":28,"properties":125},"text","The script to speak; converted to speech with the selected voice.",[],{"name":71,"required":19,"type":21,"description":127,"nullable":28,"properties":128},"Voice to synthesize the script with. Use an id from GET \u002Fapi\u002Fv1\u002Fvoices (a public or your own cloned voice).",[],{"model_id":99,"avatar_id":130,"text_script":131,"aspect_ratio":34,"resolution":105,"client_request_id":134},"avatar_123456",{"text":132,"voice_id":133,"speech_rate":119},"Welcome to VisionStory.","voice_123456","request_20260824_001",[136,171],{"status":137,"description":138,"contentType":24,"schema":139,"example":160,"examples":164,"headers":170},"200","Successful Response",{"type":140,"description":27,"nullable":28,"properties":141},"BaseSuccessResponse_CreateVideoResponse_",[142,150,155],{"name":59,"required":19,"type":143,"description":144,"nullable":19,"properties":145},"CreateVideoResponse | null","The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.",[146],{"name":147,"required":19,"type":21,"description":148,"nullable":28,"properties":149},"video_id","Identifier of the newly created video task. Poll GET \u002Fapi\u002Fv1\u002Fvideo with it to track progress.",[],{"name":151,"required":28,"type":21,"description":152,"nullable":28,"default":153,"properties":154},"message","Human-readable status message; `\"success\"` on a successful call.","success",[],{"name":156,"required":19,"type":157,"description":158,"nullable":28,"properties":159},"server_time","string · date-time","Server-side timestamp when the response was produced, in ISO 8601 format (UTC).",[],{"data":161,"message":153,"server_time":163},{"video_id":162},"example_video_id","2026-09-04T00:00:00Z",[165],{"name":153,"description":166,"summary":167,"value":168},"Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.","Successful response",{"data":169,"message":153,"server_time":163},{"video_id":162},[],{"status":172,"description":173,"contentType":24,"schema":174,"example":197,"headers":200},"default","Error response. All failures share one envelope: an `error` object with a numeric `code`, a human-readable `message`, an optional `details` string, and an optional `hint` giving an actionable next step (useful for AI agents).",{"type":175,"description":27,"nullable":28,"properties":176},"ErrorResponse",[177],{"name":178,"required":19,"type":179,"description":27,"nullable":28,"properties":180},"error","ErrorDetail",[181,186,190,194],{"name":182,"required":19,"type":183,"description":184,"nullable":28,"properties":185},"code","integer","Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.",[],{"name":187,"required":28,"type":45,"description":188,"nullable":19,"properties":189},"details","Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.",[],{"name":191,"required":28,"type":45,"description":192,"nullable":19,"properties":193},"hint","Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.",[],{"name":151,"required":19,"type":21,"description":195,"nullable":28,"properties":196},"Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.",[],{"error":198},{"code":199,"message":21,"details":21,"hint":21},1,[],[202],{"APIKeyHeader":203},[],[205,208,211],{"lang":206,"source":207},"SDK","from visionstory import VisionStoryClient, build_video_payload\n\nclient = VisionStoryClient.from_env()\npayload = build_video_payload(\n    avatar_id=\"avatar_123456\",\n    text=\"Welcome to VisionStory.\",\n    voice_id=\"voice_123456\",\n)\npayload[\"client_request_id\"] = \"request_20260824_001\"\nvideo = client.create_video(payload)\nprint(video)",{"lang":209,"source":210},"REST","import os\nimport requests\nimport base64\n\ndef encode_base64(file_path):\n    with open(file_path, 'rb') as file:\n        encoded_string = base64.b64encode(file.read()).decode('utf-8')\n    return encoded_string\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\n# audio_file_path = '\u002Fpath\u002Fto\u002Faudio.mp3'\n# payload = {\n#     \"model_id\": 'vs_character_v4',\n#     \"avatar_id\": \"4321918387609092991\",\n#     \"audio_script\": {\n#         \"inline_data\": {\n#             \"mime_type\": \"audio\u002Fmp3\",\n#             \"data\": encode_base64(audio_file_path)\n#         },\n#         \"voice_change\": True,\n#         \"voice_id\": \"Alice\",\n#         \"denoise\": True\n#     },\n#     \"aspect_ratio\": \"1:1\",\n#     \"resolution\": \"720p\",\n#     \"background_color\": \"#888888\"\n# }\n\npayload = {\n    \"model_id\": 'vs_character_v4',\n    \"avatar_id\": \"4321918387609092991\",\n    \"text_script\": {\n        \"text\": \"Hello World, this is my first test video.\",\n        \"voice_id\": \"Alice\",\n        \"speech_rate\": \"normal\"\n    },\n    \"aspect_ratio\": \"9:16\",\n    \"resolution\": \"720p\"\n}\n\nresponse = requests.post(\n    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo',  json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['video_id'])",{"lang":212,"source":213},"cURL","curl -X 'POST' \\\n      'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvideo' \\\n      -H 'accept: application\u002Fjson' \\\n      -H 'content-type: application\u002Fjson' \\\n      -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n      --data '\n{\n    \"model_id\": \"vs_character_v4\",\n    \"avatar_id\": \"4321918387609092991\",\n    \"text_script\": {\n        \"text\": \"Hello World, this is my first test video.\",\n        \"voice_id\": \"Alice\",\n        \"speech_rate\": \"normal\"\n    },\n    \"aspect_ratio\": \"9:16\",\n    \"resolution\": \"720p\"\n}\n'","\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>\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\">\"avatar_123456\"\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\">\"Welcome to VisionStory.\"\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\">\"voice_123456\"\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\">payload[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"client_request_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">] \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> \"request_20260824_001\"\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.create_video(payload)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(video)\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:#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\">\"example_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:#7EE787\">  \"message\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"success\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"server_time\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"2026-09-04T00:00:00Z\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1790231923843]