[{"data":1,"prerenderedAt":215},["ShallowReactive",2],{"reference-detail-zh-create_video_api_v1_video_post":3,"developer-code-1gcr9az":213,"developer-code-4ockr0":214},{"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":200,"codeSamples":203},"Talking Avatar Video","Videos","videos","POST","\u002Fapi\u002Fv1\u002Fvideo","create-video","生成视频","生成数字人视频，让数字人朗读通过文本转语音（`text_script`）或预录音频（`audio_script`）提供的脚本。生成异步执行，请轮询 GET \u002Fapi\u002Fv1\u002Fvideo 查询状态。成片保留 7 天，请及时下载。\n\n传入 `client_request_id` 可实现幂等重试，避免重复扣费。","create_video_api_v1_video_post",10,"\u003Cp>生成数字人视频，让数字人朗读通过文本转语音（\u003Ccode>text_script\u003C\u002Fcode>）或预录音频（\u003Ccode>audio_script\u003C\u002Fcode>）提供的脚本。生成异步执行，请轮询 GET \u002Fapi\u002Fv1\u002Fvideo 查询状态。成片保留 7 天，请及时下载。\u003C\u002Fp>\u003Cp>传入 \u003Ccode>client_request_id\u003C\u002Fcode> 可实现幂等重试，避免重复扣费。\u003C\u002Fp>",[16],{"name":17,"in":18,"required":19,"description":20,"type":21,"example":22},"X-API-Key","header",true,"你的 VisionStory API Key（`sk-vs-...`），请仅保存在服务端。可在 [API Key 管理](\u002Fapi-keys) 中创建或管理，需要 Pro 或更高方案。","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","渲染视频的输出宽高比，默认 `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","用于驱动数字人的预录旁白音频。`audio_script` 与 `text_script` 二选一。",[43,48,53,66,70],{"name":44,"required":28,"type":45,"description":46,"nullable":19,"properties":47},"audio_url","string | null","用于驱动数字人的旁白音频的公开可访问 URL。此字段与 `inline_data` 二选一。",[],{"name":49,"required":28,"type":50,"description":51,"nullable":28,"default":28,"properties":52},"denoise","boolean","设为 true 时，在生成前对上传的音频降噪。",[],{"name":54,"required":28,"type":55,"description":56,"nullable":19,"properties":57},"inline_data","InlineDataModel | null","以内嵌 base64 数据提供的旁白音频。此字段与 `audio_url` 二选一。",[58,62],{"name":59,"required":19,"type":21,"description":60,"nullable":28,"properties":61},"data","文件原始字节编码后的 base64 字符串，不包含 `data:` URI 前缀。",[],{"name":63,"required":19,"type":21,"description":64,"nullable":28,"properties":65},"mime_type","内嵌数据的 MIME 类型，网关据此区分图像、音频和视频。可接受的类型取决于具体接口，请参阅包含此对象的字段说明。数字人视频接受音频 ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav'] 和图像 ['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","设为 true 时，使用 `voice_id` 指定的声音重新合成上传的音频（声音转换），同时保留原始时间节奏。",[],{"name":71,"required":28,"type":45,"description":72,"nullable":19,"properties":73},"voice_id","`voice_change` 为 true 时用于声音转换的目标声音。请使用 GET \u002Fapi\u002Fv1\u002Fvoices 返回的 ID。",[],{"name":75,"required":19,"type":21,"description":76,"nullable":28,"properties":77},"avatar_id","朗读脚本的数字人。请使用 GET \u002Fapi\u002Fv1\u002Favatars 返回的 ID，可选择公共或自己创建的数字人。",[],{"name":79,"required":28,"type":21,"description":80,"nullable":28,"default":27,"properties":81},"background_color","可选的纯色背景，使用 6 位十六进制颜色值，例如 `#00b140`。留空时保留数字人的原始背景；设置后使用该颜色作为背景，便于色键抠像。",[],{"name":83,"required":28,"type":45,"description":84,"nullable":19,"properties":85},"client_request_id","可选的幂等键。24 小时内使用相同值重复提交，会返回原任务，不会创建新任务或再次扣费，可用于安全重试。",[],{"name":87,"required":28,"type":21,"description":88,"nullable":28,"enum":89,"default":90,"properties":95},"emotion","数字人表现的情绪，默认 `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","使用的渲染模型，请查询 GET \u002Fapi\u002Fv1\u002Fmodels。默认 `vs_character_v4`。","vs_character_v4",[],{"name":102,"required":28,"type":21,"description":103,"nullable":28,"enum":104,"default":105,"properties":108},"resolution","输出分辨率：`720p`、`1080p` 或 `2k`，默认 `720p`。分辨率越高，消耗的点数越多，渲染时间也越长。",[105,106,107],"720p","1080p","2k",[],{"name":110,"required":28,"type":111,"description":112,"nullable":19,"properties":113},"text_script","TextScript | null","文本转语音脚本，包含文本和声音。`text_script` 与 `audio_script` 二选一。",[114,122,126],{"name":115,"required":28,"type":45,"description":116,"nullable":19,"enum":117,"default":119,"properties":121},"speech_rate","合成声音的语速，默认 `normal`。",[118,119,120],"slow","normal","fast",[],{"name":123,"required":19,"type":21,"description":124,"nullable":28,"properties":125},"text","要朗读的脚本，将使用所选声音转换为语音。",[],{"name":71,"required":19,"type":21,"description":127,"nullable":28,"properties":128},"用于合成脚本的声音。请使用 GET \u002Fapi\u002Fv1\u002Fvoices 返回的 ID，可选择公共声音或自己克隆的声音。",[],{"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,170],{"status":137,"description":138,"contentType":24,"schema":139,"example":160,"examples":164,"headers":169},"200","请求成功",{"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","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[146],{"name":147,"required":19,"type":21,"description":148,"nullable":28,"properties":149},"video_id","新建视频任务的标识符。使用此 ID 轮询 GET \u002Fapi\u002Fv1\u002Fvideo 以查询进度。",[],{"name":151,"required":28,"type":21,"description":152,"nullable":28,"default":153,"properties":154},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":156,"required":19,"type":157,"description":158,"nullable":28,"properties":159},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（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":138,"value":167},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":168,"message":153,"server_time":163},{"video_id":162},[],{"status":171,"description":172,"contentType":24,"schema":173,"example":196,"headers":199},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":174,"description":27,"nullable":28,"properties":175},"ErrorResponse",[176],{"name":177,"required":19,"type":178,"description":27,"nullable":28,"properties":179},"error","ErrorDetail",[180,185,189,193],{"name":181,"required":19,"type":182,"description":183,"nullable":28,"properties":184},"code","integer","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":186,"required":28,"type":45,"description":187,"nullable":19,"properties":188},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":190,"required":28,"type":45,"description":191,"nullable":19,"properties":192},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":151,"required":19,"type":21,"description":194,"nullable":28,"properties":195},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":197},{"code":198,"message":21,"details":21,"hint":21},1,[],[201],{"APIKeyHeader":202},[],[204,207,210],{"lang":205,"source":206},"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":208,"source":209},"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":211,"source":212},"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>",1788547143930]