AI Image Generation API

The VisionStory AI Image Generation API creates or edits images from text prompts and optional reference media. The synchronous response returns an image URL that you can download or pass directly into an image-to-video workflow.

Beta. Any API key backed by an active Pro plan or above can call this endpoint. No separate capability allowlist is required.

AI image API endpoints

List image generation models

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

Each model reports its aspect ratios, resolution choices and default, prompt-length limit, reference-image limit, and live pricing. credit_per_image is the price at the default resolution; credit_by_resolution gives the price for each supported resolution. Drive your integration from this endpoint rather than hardcoding capabilities or prices.

All seven current models support 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, and 21:9. Query GET /api/v1/image/models before every model-selection flow because availability, limits, defaults, and credit costs can change.

GPT Image is available through the API. Flare favors faster generation, Sunburst targets precise edits with longer processing, and GPT Image 2 is the previous-generation option. Quality is fixed per model; there is no public quality parameter. GPT Image reference images accept PNG, JPEG (including MPO), and WebP; BMP, TIFF, GIF, and HEIC are converted to PNG by the service. Unreadable references return code 37101.

Generate or edit an AI image

Send a model_id from the models endpoint and a prompt. You can add refs to guide style or subject, or to edit an image through prompt instructions without a mask. The accepted prompt length, resolution values, default resolution, and reference-image count all depend on the selected model.

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

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

• Aspect ratio: use a value returned in params.aspect_ratio.values; the current default is 1:1.
• Resolution: use params.resolution.values and params.resolution.default. In particular, seedream-5.0-lite does not accept 1K, while seedream-5.0-pro does not accept 4K.
• Prompt: stay within params.prompt.max_length for the selected model.
• References: each entry uses asset_id, url, or inline_data; stay within the selected model's params.refs.max.
• Timeout: allow at least 180 seconds for GPT Image. The Python SDK, CLI, and local MCP use a minimum 180-second image request timeout and preserve a longer configured timeout. Do not automatically retry a timeout: the first request may still succeed and a repeat can incur another charge.

Use a generated image in a 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"
  }
}

Billing, limits, and storage

• 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: charged only on success, using credit_by_resolution for the selected resolution. credit_per_image remains the default-resolution price. The current GPT Image examples show 2 credits for 1K and 3 for 2K; read live prices before submitting. Other current models have the same price across their supported resolutions.
• Validation: an unsupported resolution returns HTTP 400; exceeding the selected model's reference limit returns HTTP 422.
• Failures: moderation refusal returns HTTP 403 with code 37100; other upstream failures return HTTP 403 with code 1. These failures happen before billing.
• Concurrency: synchronous generation is capped at a few concurrent requests per key during beta; excess requests are rejected rather than queued.

Related VisionStory API guides

• AI Video — turn a generated image into video.
• POST /api/v1/image — full request schema and error behavior.