VisionStory OpenAPI
Get API key

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/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:

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"
  }
}

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

Next steps