Image Generation

Generate or edit images from a text prompt, optionally guided by reference images. The endpoint is synchronous — the response carries the finished image URL.

Beta access. This endpoint is allowlisted during beta. If a request returns 403 / not enabled, contact your VisionStory representative. An active subscription is required.

Endpoints

Method	Path	What it does
`GET`	`/api/v1/image/models`	List image models with sizes and per-image credit cost
`POST`	`/api/v1/image`	Generate an image from a prompt (+ optional references)

Discover models

curl -s -H "X-API-Key: $VISIONSTORY_API_KEY" https://openapi.visionstory.ai/api/v1/image/models

Each model reports its aspect ratios, resolutions, reference-image limit, and credit_per_image. Current models: nano-banana (fast, economical), nano-banana-2 (balanced, strong edits), nano-banana-pro (highest quality, supports 2K). Drive your integration from this endpoint rather than hardcoding.

Generate an image

Send a model_id (from the models endpoint) and a prompt. Optionally add up to 4 refs (reference images) to guide style or subject, or to edit — editing works through instructions in the prompt plus reference images, no mask needed.

curl -s -X POST -H "X-API-Key: $VISIONSTORY_API_KEY" -H "Content-Type: application/json" -d '{"model_id": "nano-banana", "prompt": "A red panda barista in a cozy cafe, warm lighting", "aspect_ratio": "1:1", "resolution": "1K"}' https://openapi.visionstory.ai/api/v1/image

{ "data": { "url": "https://cdn.visionstory.ai/example.png" } }

Aspect ratio: one of 1:1 (default) / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9.
Resolution: 1K (default) or 2K.
References: up to 4, each asset_id / url / inline_data.

Chain into video

The returned url is a normal image URL — pass it straight into other endpoints, e.g. as first_frame or refs for AI Video:

{ "model_id": "seedance-2.0", "prompt": "the scene gently comes alive, slow camera push-in", "first_frame": { "url": "https://cdn.visionstory.ai/example.png" } }

Notes

Not stored by default. The image is returned as a URL but not added to your asset library — upload it via POST /api/v1/asset if you want a reusable asset_id.
Billing: credits per image (see credit_per_image from the models endpoint), charged only on success.
Concurrency: synchronous generation is capped at a few concurrent requests per key during beta; excess requests are rejected rather than queued.

Next steps

AI Video — turn a generated image into video.
API reference — full request schema and error codes.