Create Image — VisionStory API

Generate an image from a text prompt, optionally guided by reference images (asset_id / url / inline_data; the per-model limit is params.refs.max in GET /api/v1/image/models). 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). 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 /api/v1/asset if you want to keep it there. Credits are charged per image, only on success; some models are priced per resolution (credit_by_resolution). 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 or manage keys in API keys (Pro plan and up).

Request body

application/jsonrequired

aspect_ratiostring | nullnullable

Aspect ratio such as 1:1 / 16:9 / 9:16; defaults to 1:1

model_idstringrequired

Model id, check GET /api/v1/image/models

promptstringrequired

Text prompt; also carries edit instructions when refs are given

refsMediaRef[] | nullnullable

Reference images (asset_id / url / inline_data). The limit differs per model — read params.refs.max from GET /api/v1/image/models (4 for nano-banana-*, 6 for gpt-image-*, 10 for seedream-5.0-pro, 14 for seedream-5.0-lite).

asset_idstring | nullnullable

Asset ID from POST /api/v1/asset; use for materials reused across requests.

inline_dataInlineDataModel | nullnullable

Inline base64 media data for one-off use; not added to your asset library. Images: image/jpeg, image/jpg, image/png, image/webp, image/bmp, image/tiff, image/gif; audio: audio/wav, audio/x-wav, audio/wave, audio/mpeg, audio/mp3; video: video/mp4, video/quicktime, video/mov.

datastringrequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

mime_typestringrequired

MIME type of the inline data; the gateway uses it to tell image / audio / video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] and images ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

urlstring | nullnullable

Publicly accessible media URL for one-off use; not added to your asset library.

resolutionstring | nullnullable

Output resolution tier. Supported tiers and the default differ per model — read params.resolution from GET /api/v1/image/models. Some models are priced per tier (credit_by_resolution).

Responses

200Successful Response

application/json

dataCreateImageResponse | nullrequirednullable

The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.

cost_creditinteger

Credits charged for this image

Default: 0

heightinteger

Pixel height

Default: 0

model_idstring

Model id used

Default:

urlstringrequired

CDN URL of the generated PNG; pass it directly as a ref or first/last frame elsewhere

widthinteger

Pixel width

Default: 0

messagestring

Human-readable status message; "success" on a successful call.

Default: success

server_timestring · date-timerequired

Server-side timestamp when the response was produced, in ISO 8601 format (UTC).

defaultError 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).

application/json

errorErrorDetailrequired

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.

detailsstring | nullnullable

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 | nullnullable

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.

messagestringrequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.