VisionStory Docs
llms.txt Get API key
Image Generation/Create Image
POST/api/v1/image

Generate an image from a text prompt, optionally guided by up to 4 reference images (asset_id / url / inline_data). 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 refs, first_frame/end_frame). It is not added to your asset library — use POST /api/v1/asset if you want to keep it there. Credits are charged per image, only on success. Per-key concurrency is limited during beta; requests beyond the limit are rejected, not queued.

Headers

X-API-KeystringRequired
Your VisionStory API key (sk-vs-...), kept server-side. Create one at OpenApi (Pro plan and up).

Request body

model_idstringRequired
Model id, check GET /api/v1/image/models
promptstringRequired
Text prompt; also carries edit instructions when refs are given
aspect_ratiostring | nullOptional
Aspect ratio such as 1:1 / 16:9 / 9:16; defaults to 1:1
resolutionstring | nullOptional
Output resolution tier: 1K (default) or 2K
refsarray of MediaRef | nullOptional
Up to 4 reference images (asset_id / url / inline_data)
Show 3 propertiesHide 3 properties
asset_idstring | nullOptional
Asset ID from POST /api/v1/asset; use for materials reused across requests.
urlstring | nullOptional
Publicly accessible media URL for one-off use; not added to your asset library.
inline_dataInlineDataModel | nullOptional
Inline base64 media data for one-off use; not added to your asset library.
Show 2 propertiesHide 2 properties
mime_typestringRequired
MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].
datastringRequired
The file's raw bytes encoded as a base64 string (no data: URI prefix).

Response

200Successful Response

Successful calls return a standard envelope: the endpoint payload under data (its fields are documented below), plus a message string ("success") and an ISO 8601 server_time.

Response fields (data)
urlstringRequired
CDN URL of the generated PNG; pass it directly as a ref or first/last frame elsewhere
widthintegerOptionalDefault 0
Pixel width
heightintegerOptionalDefault 0
Pixel height
model_idstringOptionalDefault ""
Model id used
cost_creditintegerOptionalDefault 0
Credits charged for this image

Errors

All error responses share one JSON 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 (handy for AI agents).

errorErrorDetailRequired
Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead.
Show 4 propertiesHide 4 properties
codeintegerRequired
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.
messagestringRequired
Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.
detailsstring | nullOptional
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.
hintstring | nullOptional
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.