Skip to main content
GET
查询图片
GET /v1/images/{image_id} 返回生成图片所创建任务的当前状态,结构与创建接口返回的 Image 对象相同。每 2–3 秒轮询一次,直到 status 为 ready 或 failed,然后从 images[].url 下载 PNG。 只能查询自己 API 密钥创建的任务。ID 不存在或属于其他密钥时返回 404 NOT_FOUND,两种情况刻意不做区分。

请求参数

响应参数

返回 200 OK 和 Image 对象。

就绪示例

签名参数已省略:

失败示例

状态与错误码

任务只会向前走:queued → processing → ready 或 failed,不会出现 cancelled。一个任务要么 n 张全部生成,要么整体失败,不会只返回部分图片。 任务失败时 error.code 的取值: 任务失败会全额退回积分,即使失败前已生成了部分图片。重试即重新创建任务,新任务会单独预扣积分。 本接口的 HTTP 错误: HTTP 错误与失败任务的 error 使用同样的结构,外面包一层 {"error": {...}},详见错误与恢复。

耗时

2026-10-12 生产实测:1K 两张约 17–22 秒,2K 带参考图一张约 37 秒。图片逐张生成,张数越多越久;高峰时会先在 queued 排队。一个任务 15 分钟内没完成会以 SERVICE_BUSY 失败。

数据保留

  • 生成的图片在任务结束 24 小时后删除,请在此之前下载。之后本接口仍然可以查到任务,状态仍为 ready,但每个 images[].url 为 null。
  • 上传的或从 reference_image_url 拉取的参考图在 24 小时内删除。
  • 客户数据不会用于训练模型。

示例

快速入门:Viggle Image

完整的创建、轮询和下载流程。

授权

Authorization
string
header
必填

服务端 SDK 使用项目 API 密钥,Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

请求头

X-Request-Id
string

可选的调用者自定义关联 ID,最长 128 字符。服务会在响应头返回实际使用的值,便于追踪和支持排查。

Required string length: 1 - 128
X-Viggle-Source
string

可选来源标签,最长 128 字符,用于识别 SDK、集成、产品入口或内部工作流。

Required string length: 1 - 128

路径参数

image_id
string
必填

POST /v1/images 返回的图片任务公开 ID,以 img_ 开头,必须由当前 API 密钥创建。

Minimum string length: 1

响应

请求成功。

图片生成任务(img_ 前缀),创建接口与查询接口返回同一结构。状态只会向前推进:queued → processing → ready 或 failed,不会出现 cancelled。ready 前 images 始终为空,ready 后按请求顺序列出全部 n 张。一个任务要么 n 张全部生成,要么整体失败,不会只返回部分图片。

id
string
必填

图片任务公开 ID,以 img_ 开头。

Minimum string length: 1
status
enum<string>
必填

任务状态,ready 和 failed 为终态。

可用选项:
queued,
processing,
ready,
failed
model
string
必填

使用的模型,目前为 qwen。

progress
integer | null
必填

已完成张数占比:queued 为 0,processing 为 0–99,ready 为 100,failed 为 null。

必填范围: 0 <= x <= 100
images
object[]
必填

ready 前为空;ready 后按请求顺序列出全部 n 张。

created_at
string<date-time> | null
必填

创建时间,RFC 3339。

completed_at
string<date-time> | null
必填

结束时间,ready 或 failed 时有值,之前为 null。

error
object | null
必填

失败原因,只在 status 为 failed 时有值。code 为 SERVICE_BUSY(可重试:生成服务繁忙或暂时不可用,或任务 15 分钟内未完成)、TASK_FAILED(可重试:其他生成或上传失败)或 INVALID_REQUEST(不可重试:模型拒绝了请求,例如参考图无法使用)。