[{"data":1,"prerenderedAt":180},["ShallowReactive",2],{"reference-detail-zh-create_image_api_v1_image_post":3,"developer-code-1l9mcib":178,"developer-code-pdz699":179},{"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":82,"security":165,"codeSamples":168},"Image Generation","Images","images","POST","\u002Fapi\u002Fv1\u002Fimage","create-image","生成图像","根据文本提示词生成图像，可选提供最多 4 张参考图像（asset_id \u002F url \u002F inline_data）。编辑时，通过提示词中的指令配合参考图像即可，无需蒙版。此接口同步返回图像 URL，可直接将该 URL 用于其他接口（视频的 `refs`、`first_frame`\u002F`end_frame`）。生成的图像不会自动加入素材库；如需保存到素材库，请调用 POST \u002Fapi\u002Fv1\u002Fasset。按图像计费，仅成功时扣除点数。Beta 期间每个 API Key 的并发数受限，超限请求会被拒绝，不会排队。","create_image_api_v1_image_post",80,"\u003Cp>根据文本提示词生成图像，可选提供最多 4 张参考图像（asset_id \u002F url \u002F inline_data）。编辑时，通过提示词中的指令配合参考图像即可，无需蒙版。此接口同步返回图像 URL，可直接将该 URL 用于其他接口（视频的 \u003Ccode>refs\u003C\u002Fcode>、\u003Ccode>first_frame\u003C\u002Fcode>\u002F\u003Ccode>end_frame\u003C\u002Fcode>）。生成的图像不会自动加入素材库；如需保存到素材库，请调用 POST \u002Fapi\u002Fv1\u002Fasset。按图像计费，仅成功时扣除点数。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":77},"application\u002Fjson",{"type":26,"description":27,"nullable":28,"properties":29},"CreateImageRequest","",false,[30,35,39,43,73],{"name":31,"required":28,"type":32,"description":33,"nullable":19,"properties":34},"aspect_ratio","string | null","宽高比，例如 1:1 \u002F 16:9 \u002F 9:16，默认 1:1。",[],{"name":36,"required":19,"type":21,"description":37,"nullable":28,"properties":38},"model_id","模型 ID，请查询 GET \u002Fapi\u002Fv1\u002Fimage\u002Fmodels。",[],{"name":40,"required":19,"type":21,"description":41,"nullable":28,"properties":42},"prompt","文本提示词；提供 refs 时，也用于指定编辑指令。",[],{"name":44,"required":28,"type":45,"description":46,"nullable":19,"properties":47,"items":48},"refs","MediaRef[] | null","最多 4 张参考图像，通过 asset_id \u002F url \u002F inline_data 提供。",[],{"type":49,"description":50,"nullable":28,"properties":51},"MediaRef","媒体引用，必须且只能提供以下一种：`asset_id`（素材库中的素材，可跨请求复用）、`url`（单次使用的公开 URL）或 `inline_data`（单次使用的 base64 数据，不保存）。",[52,56,69],{"name":53,"required":28,"type":32,"description":54,"nullable":19,"properties":55},"asset_id","POST \u002Fapi\u002Fv1\u002Fasset 返回的素材 ID，用于跨请求复用素材。",[],{"name":57,"required":28,"type":58,"description":59,"nullable":19,"properties":60},"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。",[61,65],{"name":62,"required":19,"type":21,"description":63,"nullable":28,"properties":64},"data","文件原始字节编码后的 base64 字符串，不包含 `data:` URI 前缀。",[],{"name":66,"required":19,"type":21,"description":67,"nullable":28,"properties":68},"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":70,"required":28,"type":32,"description":71,"nullable":19,"properties":72},"url","仅供本次使用的公开可访问媒体 URL，不会加入素材库。",[],{"name":74,"required":28,"type":32,"description":75,"nullable":19,"properties":76},"resolution","输出分辨率档位：1K（默认）或 2K。",[],{"model_id":78,"prompt":79,"aspect_ratio":80,"resolution":81},"nano-banana","A red panda barista in a cozy cafe, warm lighting","1:1","1K",[83,136],{"status":84,"description":85,"contentType":24,"schema":86,"example":123,"examples":130,"headers":135},"200","请求成功",{"type":87,"description":27,"nullable":28,"properties":88},"BaseSuccessResponse_CreateImageResponse_",[89,113,118],{"name":62,"required":19,"type":90,"description":91,"nullable":19,"properties":92},"CreateImageResponse | null","当前接口的响应数据，字段定义见该接口的响应结构。仅当操作不返回数据时为 null。",[93,99,103,106,109],{"name":94,"required":28,"type":95,"description":96,"nullable":28,"default":97,"properties":98},"cost_credit","integer","生成此图像扣除的点数。",0,[],{"name":100,"required":28,"type":95,"description":101,"nullable":28,"default":97,"properties":102},"height","像素高度。",[],{"name":36,"required":28,"type":21,"description":104,"nullable":28,"default":27,"properties":105},"实际使用的模型 ID。",[],{"name":70,"required":19,"type":21,"description":107,"nullable":28,"properties":108},"生成的 PNG 图像的 CDN URL，可直接用于其他接口的参考素材或首尾帧。",[],{"name":110,"required":28,"type":95,"description":111,"nullable":28,"default":97,"properties":112},"width","像素宽度。",[],{"name":114,"required":28,"type":21,"description":115,"nullable":28,"default":116,"properties":117},"message","便于阅读的状态消息；调用成功时为 `\"success\"`。","success",[],{"name":119,"required":19,"type":120,"description":121,"nullable":28,"properties":122},"server_time","string · date-time","服务端生成响应时的时间戳，使用 ISO 8601 格式（UTC）。",[],{"data":124,"message":116,"server_time":129},{"cost_credit":125,"height":126,"model_id":127,"url":128,"width":126},2,1024,"nano-banana-2","https:\u002F\u002Fexample.com\u002Fgenerated.png","2026-09-04T00:00:00Z",[131],{"name":116,"description":132,"summary":85,"value":133},"示例仅用于说明响应结构，不代表实时账户数据或实际报价。ID 和 URL 均为占位内容。请调用模型查询及费用估算接口，获取当前可用模型和价格。",{"data":134,"message":116,"server_time":129},{"cost_credit":125,"height":126,"model_id":127,"url":128,"width":126},[],{"status":137,"description":138,"contentType":24,"schema":139,"example":161,"headers":164},"default","错误响应。所有失败均使用统一结构：`error` 对象包含数字错误码 `code`、便于阅读的 `message`、可选的 `details` 字符串，以及提供后续处理建议的可选 `hint`（便于 AI Agent 使用）。",{"type":140,"description":27,"nullable":28,"properties":141},"ErrorResponse",[142],{"name":143,"required":19,"type":144,"description":27,"nullable":28,"properties":145},"error","ErrorDetail",[146,150,154,158],{"name":147,"required":19,"type":95,"description":148,"nullable":28,"properties":149},"code","机器可读的错误码。传输层失败时对应 HTTP 状态码（例如 401、404、422、500），其他情况可能使用业务专用错误码。",[],{"name":151,"required":28,"type":32,"description":152,"nullable":19,"properties":153},"details","可选的结构化错误详情，例如 422 响应中逐字段校验错误的 JSON 字符串。无补充信息时不返回。",[],{"name":155,"required":28,"type":32,"description":156,"nullable":19,"properties":157},"hint","供用户和 AI Agent 参考的错误处理建议，例如如何修正请求或在哪里获取 API Key。可能不返回此字段。",[],{"name":114,"required":19,"type":21,"description":159,"nullable":28,"properties":160},"便于阅读的错误原因说明，可安全记录到日志或展示给最终用户；此返回值未本地化。",[],{"error":162},{"code":163,"message":21,"details":21,"hint":21},1,[],[166],{"APIKeyHeader":167},[],[169,172,175],{"lang":170,"source":171},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nimage = client.create_image({\n    \"model_id\": \"nano-banana\",\n    \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n    \"aspect_ratio\": \"1:1\",\n    \"resolution\": \"1K\",\n})\nprint(image)",{"lang":173,"source":174},"REST","import os\nimport requests\n\nresponse = requests.post(\n    \"https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fimage\",\n    headers={\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]},\n    json={\n      \"model_id\": \"nano-banana\",\n      \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n      \"aspect_ratio\": \"1:1\",\n      \"resolution\": \"1K\"\n    },\n)\nresponse.raise_for_status()\nprint(response.json())",{"lang":176,"source":177},"cURL","curl --request POST 'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fimage' \\\n  --header 'X-API-Key: $VISIONSTORY_API_KEY' \\\n  --header 'Content-Type: application\u002Fjson' \\\n  --data '{\n  \"model_id\": \"nano-banana\",\n  \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"1K\"\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\">image \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.create_image({\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\">\"nano-banana\"\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 red panda barista in a cozy cafe, warm lighting\"\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\">\"1:1\"\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\">\"1K\"\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\">(image)\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\">2\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"height\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1024\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"model_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"nano-banana-2\"\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\u002Fexample.com\u002Fgenerated.png\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"width\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\">1024\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>",1788547144544]