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. This endpoint is in beta and may change. Available to any account with an active paid subscription — no separate allowlisting.

Endpoints

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 price (credit_per_image at the default resolution, plus credit_by_resolution). Current models:

Reference-image limits differ too: 4 for nano-banana-*, 6 for gpt-image-*, 10 for seedream-5.0-pro, 14 for seedream-5.0-lite (params.refs.max).

Some models are priced per resolution. The gpt-image-* models cost more at 2K than at 1K; read credit_by_resolution from this endpoint. For the other models every resolution has the same price. The cost_credit in the generation response is always what was actually charged.

GPT Image models are slower — typically 20–60 seconds, occasionally up to 3 minutes, and a prompt rejected by content moderation can take about 45 seconds to come back. Set your client timeout to at least 3 minutes for these models.

Resolutions differ per model — seedream-5.0-lite has no 1K tier and seedream-5.0-pro has no 4K tier, so read params.resolution from this endpoint rather than hardcoding 1K. Omit resolution and each model uses its own default. The legacy nano-banana request ID remains accepted and routes to nano-banana-2 at the same live price.

Generate an image

Send a model_id (from the models endpoint) and a prompt. Optionally add 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-2", "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: per model — see the table above, or params.resolution from the models endpoint. gpt-image-* models support 1K and 2K only.
• References: per model — 4 for nano-banana-*, 6 for gpt-image-*, 10 for seedream-5.0-pro, 14 for seedream-5.0-lite; each asset_id / url / inline_data.
• Prompt length: params.prompt.max_length per model (5000 characters for nano-banana-*, 3000 for seedream-*).

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 at the resolution you request (see credit_by_resolution from the models endpoint), charged only on success. The cost_credit in the response is the amount actually charged.
• 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.