AI 图像生成 API

VisionStory AI 图像生成 API 根据文本提示和可选参考素材生成或编辑图像。同步响应会返回图像 URL，你可以直接下载，也可以将其用于图生视频流程。

Beta。 只要账户拥有有效的 Pro 或更高等级订阅，其 API Key 即可调用此接口，无需额外申请能力白名单。

AI 图像接口

查询图像生成模型

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

每个模型会返回画面比例、可用分辨率及默认值、提示词长度上限、参考图数量上限和实时价格。credit_per_image 表示默认分辨率的价格，credit_by_resolution 提供每个可用分辨率的价格。接入时应读取此接口的返回值，不要写死模型能力或价格。

当前七个模型均支持 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9 和 21:9。模型可用性、限制、默认值和点数成本可能调整，因此每次设计模型选择流程前，都应查询 GET /api/v1/image/models。

GPT Image 可通过 API 调用。Flare 侧重更快的生成速度，Sunburst 侧重精确编辑、处理时间更长，GPT Image 2 则是上一代模型。质量档位由模型固定，不提供公开的质量参数。GPT Image 参考图支持 PNG、JPEG（含 MPO）和 WebP；服务会将 BMP、TIFF、GIF 和 HEIC 转换为 PNG。无法读取的参考图返回错误码 37101。

生成或编辑 AI 图像

传入模型接口返回的 model_id 和 prompt。你可以使用 refs 指定风格或主体，也可以通过提示词与参考图直接编辑图像，无需蒙版。提示词长度、可用分辨率、默认分辨率和参考图数量均取决于所选模型。

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

• 画面比例： 使用 params.aspect_ratio.values 返回的值；当前默认值为 1:1。
• 分辨率： 使用 params.resolution.values 和 params.resolution.default。特别注意，seedream-5.0-lite 不接受 1K，seedream-5.0-pro 不接受 4K。
• 提示词： 不要超过所选模型的 params.prompt.max_length。
• 参考图： 每项使用 asset_id、url 或 inline_data，数量不得超过所选模型的 params.refs.max。
• 超时： GPT Image 至少需要 180 秒的客户端超时。Python SDK、CLI 和本地 MCP 的图像请求超时至少为 180 秒，配置更长时会保留该值。不要自动重试超时请求：首次请求可能仍会成功，重复提交可能再次扣费。

将生成的图像用于视频

返回的 url 是普通图像地址，可以直接传给其他接口，例如作为 AI 视频的 first_frame 或 refs：

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

计费、限制与存储

• 默认不加入素材库。 接口返回图像 URL，但不会自动保存到素材库。如需可复用的 asset_id，请通过 POST /api/v1/asset 上传。
• 计费： 仅成功时扣费，按所选分辨率读取 credit_by_resolution。credit_per_image 仍表示默认分辨率的价格。当前 GPT Image 示例为 1K 2 点、2K 3 点；提交前请查询实时价格。其他当前模型在各自支持的分辨率下价格相同。
• 参数校验： 不支持的分辨率返回 HTTP 400；参考图数量超过所选模型上限时返回 HTTP 422。
• 失败语义： 内容审核拒绝返回 HTTP 403 和错误码 37100；其他上游失败返回 HTTP 403 和错误码 1。这些失败均发生在扣费之前。
• 并发： Beta 期间，每个 API Key 的同步生成并发数较低；超出限制的请求会被拒绝，不会排队。

相关 VisionStory API 指南

• AI 视频 — 将生成的图像转为视频。
• POST /api/v1/image — 查看完整请求结构与错误语义。