[{"data":1,"prerenderedAt":181},["ShallowReactive",2],{"reference-detail-en-create_image_api_v1_image_post":3,"developer-code-17jnvd5":179,"developer-code-pdz699":180},{"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":166,"codeSamples":169},"Image Generation","Images","images","POST","\u002Fapi\u002Fv1\u002Fimage","create-image","Create Image","Generate an image from a text prompt, optionally guided by reference images\n(asset_id \u002F url \u002F inline_data; the per-model limit is `params.refs.max` in GET \u002Fapi\u002Fv1\u002Fimage\u002Fmodels).\nEditing works through instructions in the prompt plus reference images — no mask needed.\nSynchronous: the response contains the image URL directly, and you can pass that URL straight into\nother endpoints (video `refs`, `first_frame`\u002F`end_frame`). GPT Image models are slower (often 20–60\nseconds) — set a client timeout of at least 3 minutes. It is not added to your asset library — use\nPOST \u002Fapi\u002Fv1\u002Fasset if you want to keep it there. Credits are charged per image, only on success; some\nmodels are priced per resolution (`credit_by_resolution`). Per-key concurrency is limited during beta;\nrequests beyond the limit are rejected, not queued.","create_image_api_v1_image_post",80,"\u003Cp>Generate an image from a text prompt, optionally guided by reference images (asset_id \u002F url \u002F inline_data; the per-model limit is \u003Ccode>params.refs.max\u003C\u002Fcode> in GET \u002Fapi\u002Fv1\u002Fimage\u002Fmodels). Editing works through instructions in the prompt plus reference images — no mask needed. Synchronous: the response contains the image URL directly, and you can pass that URL straight into other endpoints (video \u003Ccode>refs\u003C\u002Fcode>, \u003Ccode>first_frame\u003C\u002Fcode>\u002F\u003Ccode>end_frame\u003C\u002Fcode>). GPT Image models are slower (often 20–60 seconds) — set a client timeout of at least 3 minutes. It is not added to your asset library — use POST \u002Fapi\u002Fv1\u002Fasset if you want to keep it there. Credits are charged per image, only on success; some models are priced per resolution (\u003Ccode>credit_by_resolution\u003C\u002Fcode>). Per-key concurrency is limited during beta; requests beyond the limit are rejected, not queued.\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":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","Aspect ratio such as 1:1 \u002F 16:9 \u002F 9:16; defaults to 1:1",[],{"name":36,"required":19,"type":21,"description":37,"nullable":28,"properties":38},"model_id","Model id, check GET \u002Fapi\u002Fv1\u002Fimage\u002Fmodels",[],{"name":40,"required":19,"type":21,"description":41,"nullable":28,"properties":42},"prompt","Text prompt; also carries edit instructions when refs are given",[],{"name":44,"required":28,"type":45,"description":46,"nullable":19,"properties":47,"items":48},"refs","MediaRef[] | null","Reference images (asset_id \u002F url \u002F inline_data). The limit differs per model — read `params.refs.max` from GET \u002Fapi\u002Fv1\u002Fimage\u002Fmodels (4 for `nano-banana-*`, 6 for `gpt-image-*`, 10 for `seedream-5.0-pro`, 14 for `seedream-5.0-lite`).",[],{"type":49,"description":50,"nullable":28,"properties":51},"MediaRef","A media reference — provide exactly one of: `asset_id` (from the asset library, reusable across\nrequests), `url` (one-off public URL), or `inline_data` (one-off base64, not stored).",[52,56,69],{"name":53,"required":28,"type":32,"description":54,"nullable":19,"properties":55},"asset_id","Asset ID from POST \u002Fapi\u002Fv1\u002Fasset; use for materials reused across requests.",[],{"name":57,"required":28,"type":58,"description":59,"nullable":19,"properties":60},"inline_data","InlineDataModel | null","Inline base64 media data for one-off use; not added to your asset library. Images: image\u002Fjpeg, image\u002Fjpg, image\u002Fpng, image\u002Fwebp, image\u002Fbmp, image\u002Ftiff, image\u002Fgif; audio: audio\u002Fwav, audio\u002Fx-wav, audio\u002Fwave, audio\u002Fmpeg, audio\u002Fmp3; video: video\u002Fmp4, video\u002Fquicktime, video\u002Fmov.",[61,65],{"name":62,"required":19,"type":21,"description":63,"nullable":28,"properties":64},"data","The file's raw bytes encoded as a base64 string (no `data:` URI prefix).",[],{"name":66,"required":19,"type":21,"description":67,"nullable":28,"properties":68},"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":70,"required":28,"type":32,"description":71,"nullable":19,"properties":72},"url","Publicly accessible media URL for one-off use; not added to your asset library.",[],{"name":74,"required":28,"type":32,"description":75,"nullable":19,"properties":76},"resolution","Output resolution tier. Supported tiers and the default differ per model — read `params.resolution` from GET \u002Fapi\u002Fv1\u002Fimage\u002Fmodels. Some models are priced per tier (`credit_by_resolution`).",[],{"model_id":78,"prompt":79,"aspect_ratio":80,"resolution":81},"seedream-5.0-lite","A red panda barista in a cozy cafe, warm lighting","1:1","2K",[83,137],{"status":84,"description":85,"contentType":24,"schema":86,"example":123,"examples":130,"headers":136},"200","Successful Response",{"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","The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.",[93,99,103,106,109],{"name":94,"required":28,"type":95,"description":96,"nullable":28,"default":97,"properties":98},"cost_credit","integer","Credits charged for this image",0,[],{"name":100,"required":28,"type":95,"description":101,"nullable":28,"default":97,"properties":102},"height","Pixel height",[],{"name":36,"required":28,"type":21,"description":104,"nullable":28,"default":27,"properties":105},"Model id used",[],{"name":70,"required":19,"type":21,"description":107,"nullable":28,"properties":108},"CDN URL of the generated PNG; pass it directly as a ref or first\u002Flast frame elsewhere",[],{"name":110,"required":28,"type":95,"description":111,"nullable":28,"default":97,"properties":112},"width","Pixel width",[],{"name":114,"required":28,"type":21,"description":115,"nullable":28,"default":116,"properties":117},"message","Human-readable status message; `\"success\"` on a successful call.","success",[],{"name":119,"required":19,"type":120,"description":121,"nullable":28,"properties":122},"server_time","string · date-time","Server-side timestamp when the response was produced, in ISO 8601 format (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":133,"value":134},"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":135,"message":116,"server_time":129},{"cost_credit":125,"height":126,"model_id":127,"url":128,"width":126},[],{"status":138,"description":139,"contentType":24,"schema":140,"example":162,"headers":165},"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":141,"description":27,"nullable":28,"properties":142},"ErrorResponse",[143],{"name":144,"required":19,"type":145,"description":27,"nullable":28,"properties":146},"error","ErrorDetail",[147,151,155,159],{"name":148,"required":19,"type":95,"description":149,"nullable":28,"properties":150},"code","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":152,"required":28,"type":32,"description":153,"nullable":19,"properties":154},"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":156,"required":28,"type":32,"description":157,"nullable":19,"properties":158},"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":114,"required":19,"type":21,"description":160,"nullable":28,"properties":161},"Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.",[],{"error":163},{"code":164,"message":21,"details":21,"hint":21},1,[],[167],{"APIKeyHeader":168},[],[170,173,176],{"lang":171,"source":172},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nimage = client.create_image({\n    \"model_id\": \"seedream-5.0-lite\",\n    \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n    \"aspect_ratio\": \"1:1\",\n    \"resolution\": \"2K\",\n})\nprint(image)",{"lang":174,"source":175},"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\": \"seedream-5.0-lite\",\n      \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n      \"aspect_ratio\": \"1:1\",\n      \"resolution\": \"2K\"\n    },\n)\nresponse.raise_for_status()\nprint(response.json())",{"lang":177,"source":178},"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\": \"seedream-5.0-lite\",\n  \"prompt\": \"A red panda barista in a cozy cafe, warm lighting\",\n  \"aspect_ratio\": \"1:1\",\n  \"resolution\": \"2K\"\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\">\"seedream-5.0-lite\"\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\">\"2K\"\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>",1790231924570]