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
| 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/modelsEach model reports its aspect ratios, resolutions, reference-image limit, and price (credit_per_image at the default resolution, plus credit_by_resolution). Current models:
model_id |
Best for | Resolutions |
|---|---|---|
nano-banana-2 |
Balanced quality and speed, strong instruction-following edits | 1K (default), 2K |
nano-banana-pro |
Highest quality tier, detailed scenes | 1K (default), 2K |
seedream-5.0-lite |
Fast and economical; 4K costs the same as 2K | 2K (default), 4K |
seedream-5.0-pro |
Higher-fidelity Seedream tier | 1K (default), 2K |
gpt-image-2.5-flare |
OpenAI GPT Image 2.5, fast high-quality generation and edits | 1K (default), 2K |
gpt-image-2.5-sunburst |
OpenAI GPT Image 2.5, most capable for precise edits; slower than Flare | 1K (default), 2K |
gpt-image-2 |
OpenAI GPT Image 2, previous generation | 1K (default), 2K |
Reference-image limits differ too: 14 for nano-banana-*, 16 for gpt-image-2, 6 for gpt-image-2.5-*, 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 2 charges for additional references. The resolution price (credit_by_resolution) is the base price, including the first 6 reference images. Only gpt-image-2 adds ceil(max(0, ref_count - 6) / 3) credits per generated image. The models response declares this as reference_pricing: included_refs=6, refs_per_credit=3, credit_per_step=1. Other models return null and have no reference surcharge.
| Reference images | Added credits | Total with base 1K=2 / 2K=3 |
|---|---|---|
| 0–6 | 0 | 2 / 3 |
| 7–9 | 1 | 3 / 4 |
| 10–12 | 2 | 4 / 5 |
| 13–15 | 3 | 5 / 6 |
| 16 | 4 | 6 / 7 |
These totals are examples; fetch the current base prices from the models endpoint. Sending 17 references returns 422. Generation failures are not charged. More references also take longer to fetch; allow extra client timeout for downloads.
Any model can take up to 3 minutes. GPT Image models typically take 20–60 seconds, nano-banana-* and seedream-* can also run close to 3 minutes at higher resolutions or with many references, and a prompt rejected by content moderation can take about 45 seconds to come back. Set your client timeout to at least 4 minutes for every image model. A model that does not return in time fails with 504 (37008) and is not charged — see Errors below.
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.resolutionfrom the models endpoint.gpt-image-*models support1Kand2Konly. - References: per model — 14 for
nano-banana-*, 16 forgpt-image-2, 6 forgpt-image-2.5-*, 10 forseedream-5.0-pro, 14 forseedream-5.0-lite; eachasset_id/url/inline_data. - Prompt length:
params.prompt.max_lengthper model (5000 characters fornano-banana-*, 3000 forseedream-*).
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"
}
}Errors
| HTTP | error.code | Meaning |
|---|---|---|
| 400 | 400 | Invalid parameters — unknown model_id, empty prompt, prompt over the model's params.prompt.max_length, unsupported aspect_ratio / resolution, or reference media that cannot be fetched or decoded |
| 422 | — | Malformed request body (unknown fields, missing required fields, more references than the model's params.refs.max) |
| 401 | 401 | Missing or unrecognised API key — check the X-API-Key header |
| 403 | 42000 | Key is valid, but the account has no active Pro (or above) subscription — renew, the same key resumes working |
| 403 | 30309 | Not enough paid credits — bonus credits cannot be used for image generation. error.details carries paid_credit_balance and credit_needed. Nothing was charged |
| 403 | 37100 | Content rejected by the model provider. When the provider reports it, error.details carries stage: input (prompt or reference images) or output (generated image). Nothing was charged; retrying the same input usually fails again — change the prompt or references |
| 403 | 37101 | Invalid reference image — not found, not an image, or unreadable |
| 403 | 37110 | Prompt rejected by the platform content policy. error.details carries risk_type. Edit the prompt before retrying. No credits are charged |
| 403 | 37111 | Reference image rejected by the platform content policy. error.details carries risk_type. Change the reference before retrying. No credits are charged |
| 429 | 429 | Too many concurrent image requests for this key — wait for in-flight requests to finish |
| 504 | 37008 | The model did not return a result within the time limit (timeout_sec in error.details). Nothing was charged; retry once, and if it keeps timing out use fewer references or a lower resolution |
| 502 | 37009 | The model provider returned an error or no image. Nothing was charged; retry once |
| 403 | 1 | Unexpected server error — retry later |
error.details, when present, is a JSON-encoded string such as {"timeout_sec": 180}; parse it to read these fields. 37008, 37009, 37100, and 30309 are all returned before any credits are deducted, so nothing is charged. These errors also carry an error.hint with the next step. After 37008 or 37009, retry once with the same parameters; do not send the same request again while an earlier one is still running.
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/assetif you want a reusableasset_id. - Billing: credits per image at the resolution you request (see
credit_by_resolutionfrom the models endpoint), charged only on success. Thecost_creditin 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.