Create Image — VisionStory API

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 or manage keys in API keys (Pro plan and up).

Request body

application/jsonrequired

aspect_ratiostring | nullnullable

Output frame shape. Supported values are listed below; defaults to 1:1.

Values: 1:12:33:23:44:34:55:49:1616:921:9

Default: 1:1

model_idstringrequired

Choose an image model. The values below are the currently supported IDs; query GET /api/v1/image/models for live availability and credit cost.

Values: nano-banananano-banana-2nano-banana-pro

promptstringrequired

Describe the image to generate, or the edits to apply when refs are present. Length: 1–5000 characters.

refsMediaRef[] | nullnullable

Up to 4 reference images for image editing. Each item must provide exactly one of asset_id, url, or inline_data.

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.

datastringrequired

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

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'].

urlstring | nullnullable

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

resolutionstring | nullnullable

Output resolution tier. 2K costs more credits; defaults to 1K.

Values: 1K2K

Default: 1K

Responses

200Successful Response

application/json

dataCreateImageResponse | nullrequirednullable

The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete.

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.