[{"data":1,"prerenderedAt":216},["ShallowReactive",2],{"reference-detail-zh-create_ai_video_api_v1_ai_video_post":3,"developer-code-nnra5b":214,"developer-code-2cu7l8":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":125,"security":201,"codeSamples":204},"AI Video","AI Videos","ai-videos","POST","\u002Fapi\u002Fv1\u002Fai_video","create-ai-video","生成 AI 视频","使用前沿 AI 模型生成视频。提供 `first_frame`（可选 `end_frame`）进行图生视频，提供 `refs` 进行多模态文生视频，两者都不提供则进行纯文生视频。提交时扣除点数，生成失败时自动退还。通过轮询 GET \u002Fapi\u002Fv1\u002Fai_video 查询进度。\n\nBeta：所有有效付费订阅账户均可使用。Beta 期间每个 API Key 的并发数受限，超限提交会被拒绝，不会排队。","create_ai_video_api_v1_ai_video_post",60,"\u003Cp>使用前沿 AI 模型生成视频。提供 \u003Ccode>first_frame\u003C\u002Fcode>（可选 \u003Ccode>end_frame\u003C\u002Fcode>）进行图生视频，提供 \u003Ccode>refs\u003C\u002Fcode> 进行多模态文生视频，两者都不提供则进行纯文生视频。提交时扣除点数，生成失败时自动退还。通过轮询 GET \u002Fapi\u002Fv1\u002Fai_video 查询进度。\u003C\u002Fp>\u003Cp>Beta：所有有效付费订阅账户均可使用。Beta 期间每个 API Key 的并发数受限，超限提交会被拒绝，不会排队。\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":118},"application\u002Fjson",{"type":26,"description":27,"nullable":28,"properties":29},"CreateAiVideoRequest","",false,[30,35,39,44,70,83,88,92,96,114],{"name":31,"required":28,"type":32,"description":33,"nullable":19,"properties":34},"aspect_ratio","string | null","宽高比，例如 `16:9` \u002F `9:16` \u002F `1:1`，或使用 `adaptive` 让模型跟随输入素材。可选值因模型而异，默认使用模型默认值。`wan-3.0` 设置 `refs` 时始终跟随参考素材，因此同时指定两者会返回 400。",[],{"name":36,"required":28,"type":32,"description":37,"nullable":19,"properties":38},"client_request_id","可选的幂等键。24 小时内使用相同值重复提交，会返回原任务，不会创建新任务或再次扣费，可用于安全重试。",[],{"name":40,"required":28,"type":41,"description":42,"nullable":19,"properties":43},"duration_sec","integer | null","视频时长，单位为秒。可选值因模型而异（请查询 GET \u002Fapi\u002Fv1\u002Fai_video\u002Fmodels），默认使用模型默认值。时长越长，消耗的点数越多。",[],{"name":45,"required":28,"type":46,"description":47,"nullable":19,"properties":48},"end_frame","MediaRef | null","媒体引用，必须且只能提供以下一种：`asset_id`（素材库中的素材，可跨请求复用）、`url`（单次使用的公开 URL）或 `inline_data`（单次使用的 base64 数据，不保存）。",[49,53,66],{"name":50,"required":28,"type":32,"description":51,"nullable":19,"properties":52},"asset_id","POST \u002Fapi\u002Fv1\u002Fasset 返回的素材 ID，用于跨请求复用素材。",[],{"name":54,"required":28,"type":55,"description":56,"nullable":19,"properties":57},"inline_data","InlineDataModel | null","仅供本次使用的内嵌 base64 媒体数据，不会加入素材库。图像支持 image\u002Fjpeg、image\u002Fjpg、image\u002Fpng、image\u002Fwebp、image\u002Fbmp、image\u002Ftiff、image\u002Fgif；音频支持 audio\u002Fwav、audio\u002Fx-wav、audio\u002Fwave、audio\u002Fmpeg、audio\u002Fmp3；视频支持 video\u002Fmp4、video\u002Fquicktime、video\u002Fmov。",[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":32,"description":68,"nullable":19,"properties":69},"url","仅供本次使用的公开可访问媒体 URL，不会加入素材库。",[],{"name":71,"required":28,"type":46,"description":47,"nullable":19,"properties":72},"first_frame",[73,75,81],{"name":50,"required":28,"type":32,"description":51,"nullable":19,"properties":74},[],{"name":54,"required":28,"type":55,"description":56,"nullable":19,"properties":76},[77,79],{"name":59,"required":19,"type":21,"description":60,"nullable":28,"properties":78},[],{"name":63,"required":19,"type":21,"description":64,"nullable":28,"properties":80},[],{"name":67,"required":28,"type":32,"description":68,"nullable":19,"properties":82},[],{"name":84,"required":28,"type":85,"description":86,"nullable":19,"properties":87},"generate_audio","boolean | null","是否生成原生音轨；所有模型均默认为 true，且不影响价格。`kling-3.0-omni` 不允许同时启用此选项并提供视频参考素材，否则返回 400。",[],{"name":89,"required":19,"type":21,"description":90,"nullable":28,"properties":91},"model_id","用于生成的模型。请使用 GET \u002Fapi\u002Fv1\u002Fai_video\u002Fmodels 返回的 ID，例如 `seedance-2.0`。",[],{"name":93,"required":19,"type":21,"description":94,"nullable":28,"properties":95},"prompt","描述要生成的视频的提示词。图生视频时，用于描述施加于 `first_frame` 的运动。",[],{"name":97,"required":28,"type":98,"description":99,"nullable":19,"properties":100,"items":101},"refs","MediaRef[] | null","用于引导文生视频的多模态参考素材（图像\u002F视频\u002F音频）。仅当 GET \u002Fapi\u002Fv1\u002Fai_video\u002Fmodels 中该模型的 `refs.max` 大于 0 时才支持；其中的 `refs.max_per_kind` 和 `refs.total_duration_sec_max` 给出了各类型限制。参考素材不影响价格。与 `first_frame` 互斥。",[],{"type":102,"description":47,"nullable":28,"properties":103},"MediaRef",[104,106,112],{"name":50,"required":28,"type":32,"description":51,"nullable":19,"properties":105},[],{"name":54,"required":28,"type":55,"description":56,"nullable":19,"properties":107},[108,110],{"name":59,"required":19,"type":21,"description":60,"nullable":28,"properties":109},[],{"name":63,"required":19,"type":21,"description":64,"nullable":28,"properties":111},[],{"name":67,"required":28,"type":32,"description":68,"nullable":19,"properties":113},[],{"name":115,"required":28,"type":32,"description":116,"nullable":19,"properties":117},"resolution","输出分辨率，例如 `480p` \u002F `720p` \u002F `1080p` \u002F `4k`。可选值因模型而异：4K 仅限 `kling-3.0`；所有 Seedance 和 Wan 模型均支持 480p，Kling 不支持。默认使用模型默认值：仅 `kling-3.0-omni` 默认 1080p，其他模型均默认 720p。分辨率越高，消耗的点数越多。",[],{"model_id":119,"prompt":120,"duration_sec":121,"aspect_ratio":122,"resolution":123,"generate_audio":19,"client_request_id":124},"seedance-2.0","A corgi surfing at sunset, cinematic lighting",8,"9:16","1080p","request_20260824_001",[126,172],{"status":127,"description":128,"contentType":24,"schema":129,"example":161,"examples":166,"headers":171},"200","请求成功",{"type":130,"description":27,"nullable":28,"properties":131},"BaseSuccessResponse_CreateAiVideoResponse_",[132,151,156],{"name":59,"required":19,"type":133,"description":134,"nullable":19,"properties":135},"CreateAiVideoResponse | null","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[136,142,147],{"name":137,"required":28,"type":138,"description":139,"nullable":28,"default":140,"properties":141},"cost_credit","integer","提交任务时扣除的点数；生成失败时自动退还。",0,[],{"name":143,"required":28,"type":21,"description":144,"nullable":28,"default":145,"properties":146},"status","初始任务状态，创建后始终为 `queued`。","queued",[],{"name":148,"required":19,"type":21,"description":149,"nullable":28,"properties":150},"video_id","已创建任务的标识符。使用此 ID 轮询 GET \u002Fapi\u002Fv1\u002Fai_video 以查询进度。",[],{"name":152,"required":28,"type":21,"description":153,"nullable":28,"default":154,"properties":155},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":157,"required":19,"type":158,"description":159,"nullable":28,"properties":160},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。",[],{"data":162,"message":154,"server_time":165},{"cost_credit":163,"status":145,"video_id":164},16,"example_ai_video_id","2026-09-04T00:00:00Z",[167],{"name":154,"description":168,"summary":128,"value":169},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":170,"message":154,"server_time":165},{"cost_credit":163,"status":145,"video_id":164},[],{"status":173,"description":174,"contentType":24,"schema":175,"example":197,"headers":200},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":176,"description":27,"nullable":28,"properties":177},"ErrorResponse",[178],{"name":179,"required":19,"type":180,"description":27,"nullable":28,"properties":181},"error","ErrorDetail",[182,186,190,194],{"name":183,"required":19,"type":138,"description":184,"nullable":28,"properties":185},"code","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":187,"required":28,"type":32,"description":188,"nullable":19,"properties":189},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":191,"required":28,"type":32,"description":192,"nullable":19,"properties":193},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":152,"required":19,"type":21,"description":195,"nullable":28,"properties":196},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"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\n\nclient = VisionStoryClient.from_env()\nvideo = client.create_ai_video({\n    \"model_id\": \"seedance-2.0\",\n    \"prompt\": \"A corgi surfing at sunset, cinematic lighting\",\n    \"duration_sec\": 8,\n    \"aspect_ratio\": \"9:16\",\n    \"resolution\": \"1080p\",\n    \"generate_audio\": True,\n    \"client_request_id\": \"request_20260824_001\",\n})\nprint(video)",{"lang":209,"source":210},"REST","import os\nimport requests\n\nresponse = requests.post(\n    \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fai_video\",\n    headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n    json={\n      \"model_id\": \"seedance-2.0\",\n      \"prompt\": \"A corgi surfing at sunset, cinematic lighting\",\n      \"duration_sec\": 8,\n      \"aspect_ratio\": \"9:16\",\n      \"resolution\": \"1080p\",\n      \"generate_audio\": True,\n      \"client_request_id\": \"request_20260824_001\"\n    },\n)\nresponse.raise_for_status()\nprint(response.json())",{"lang":212,"source":213},"cURL","curl --request POST 'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fai_video' \\\n  --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n  --header 'Content-Type: application\u002Fjson' \\\n  --data '{\n  \"model_id\": \"seedance-2.0\",\n  \"prompt\": \"A corgi surfing at sunset, cinematic lighting\",\n  \"duration_sec\": 8,\n  \"aspect_ratio\": \"9:16\",\n  \"resolution\": \"1080p\",\n  \"generate_audio\": true,\n  \"client_request_id\": \"request_20260824_001\"\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\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\">video \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.create_ai_video({\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"model_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"seedance-2.0\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"prompt\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"A corgi surfing at sunset, cinematic lighting\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"duration_sec\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">8\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"aspect_ratio\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"9:16\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"resolution\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"1080p\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"generate_audio\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">True\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"client_request_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"request_20260824_001\"\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:#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\">    \"cost_credit\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">16\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"status\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"queued\"\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_ai_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>",1788547144502]