> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询图片

> 获取图片生成任务的当前状态，就绪后获取 PNG 下载链接。

`GET /v1/images/{image_id}` 返回[生成图片](/zh/v1/api-reference/images/create)所创建任务的当前状态，结构与创建接口返回的 Image 对象相同。每 2–3 秒轮询一次，直到 `status` 为 `ready` 或 `failed`，然后从 `images[].url` 下载 PNG。

只能查询自己 API 密钥创建的任务。ID 不存在或属于其他密钥时返回 `404 NOT_FOUND`，两种情况刻意不做区分。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | :-: | - |
| `image_id` | string | 是 | 生成图片返回的完整任务 ID，以 `img_` 开头。 |

## 响应参数

返回 `200 OK` 和 Image 对象。

| 字段 | 类型 | 说明 |
| - | - | - |
| `id` | string | 任务 ID，以 `img_` 开头。 |
| `status` | string | `queued`、`processing`、`ready` 或 `failed`，见[状态与错误码](#status-and-errors)。 |
| `model` | string | 使用的模型，目前为 `qwen`。 |
| `progress` | integer 或 null | 已完成张数占比：`queued` 为 `0`，`processing` 为 0–99，`ready` 为 `100`，`failed` 为 `null`。 |
| `images` | array | `ready` 前始终为空；`ready` 后按请求顺序列出全部 `n` 张。 |
| `images[].url` | string 或 null | PNG 的签名下载链接，**1 小时**内有效，过期后再查询一次即可拿到新链接。文件在[保留期](#data-retention)结束被清理后为 `null`。 |
| `images[].width` / `images[].height` | integer | 实际尺寸（像素），见[输出尺寸](/zh/v1/api-reference/images/create#output-sizes)。 |
| `images[].seed` | integer | 这张图实际使用的 seed。 |
| `created_at` | string 或 null | 创建时间，RFC 3339。 |
| `completed_at` | string 或 null | 结束时间，`ready` 或 `failed` 时有值。 |
| `error` | object 或 null | 失败原因，只在 `failed` 时有值。 |

### 就绪示例

签名参数已省略：

```json theme={null}
{
  "id": "img_b16a190d-2d44-41a0-8056-ef68183c3b9e",
  "status": "ready",
  "model": "qwen",
  "progress": 100,
  "images": [
    {"url": "https://storage.googleapis.com/viggle/image-generation/b16a190d-2d44-41a0-8056-ef68183c3b9e/0.png?X-Goog-Signature=...", "width": 1376, "height": 768, "seed": 0},
    {"url": "https://storage.googleapis.com/viggle/image-generation/b16a190d-2d44-41a0-8056-ef68183c3b9e/1.png?X-Goog-Signature=...", "width": 1376, "height": 768, "seed": 1}
  ],
  "created_at": "2026-10-12T08:20:00Z",
  "completed_at": "2026-10-12T08:20:22Z",
  "error": null
}
```

### 失败示例

```json theme={null}
{
  "id": "img_b16a190d-2d44-41a0-8056-ef68183c3b9e",
  "status": "failed",
  "model": "qwen",
  "progress": null,
  "images": [],
  "created_at": "2026-10-12T08:20:00Z",
  "completed_at": "2026-10-12T08:35:00Z",
  "error": {
    "code": "SERVICE_BUSY",
    "message": "The image service is busy; try again later.",
    "retryable": true,
    "request_id": null,
    "details": {},
    "remediation": { "action": "retry", "retry_after_ms": null }
  }
}
```

<a id="status-and-errors" />

## 状态与错误码

任务只会向前走：`queued` → `processing` → `ready` 或 `failed`，不会出现 `cancelled`。一个任务要么 `n` 张全部生成，要么整体失败，不会只返回部分图片。

| `status` | 含义 |
| - | - |
| `queued` | 已接受，在等 GPU；高峰时会在这个状态停留一段时间。 |
| `processing` | 正在逐张生成，`progress` 随每张完成而增加。 |
| `ready` | 全部完成，`images` 已填充。 |
| `failed` | 失败，原因见 `error`。 |

任务失败时 `error.code` 的取值：

| `code` | `retryable` | 什么时候出现 | 建议 |
| - | :-: | - | - |
| `SERVICE_BUSY` | `true` | 生成服务繁忙或暂时不可用，或任务 15 分钟内未完成。 | 稍后用同样的参数重新创建。 |
| `TASK_FAILED` | `true` | 其他生成或上传失败。 | 重新创建；反复出现请带上任务 `id` 联系我们。 |
| `INVALID_REQUEST` | `false` | 模型拒绝了这个请求，例如参考图无法使用。 | 调整参数或参考图后再试。 |

任务失败会全额退回积分，即使失败前已生成了部分图片。重试即重新创建任务，新任务会单独预扣积分。

本接口的 HTTP 错误：

| HTTP | `code` | 含义 |
| - | - | - |
| `401` | `UNAUTHENTICATED` | 缺少或无效的 API 密钥。 |
| `404` | `NOT_FOUND` | 任务不存在，或不属于当前密钥。 |
| `429` | `RATE_LIMITED` | 请求过多，稍后重试。 |
| `500` | `INTERNAL_ERROR` | 服务端内部错误，可重试。 |
| `503` | `SERVICE_BUSY` | 服务暂时不可用，可重试。 |

HTTP 错误与失败任务的 `error` 使用同样的结构，外面包一层 `{"error": {...}}`，详见[错误与恢复](/zh/v1/production/errors)。

## 耗时

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

<a id="data-retention" />

## 数据保留

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

## 示例

<CodeGroup>
  ```bash cURL theme={null}
  curl https://apis.viggle.ai/v1/images/img_b16a190d-2d44-41a0-8056-ef68183c3b9e \
    -H "Authorization: Bearer $VIGGLE_API_KEY"
  ```

  ```python Python theme={null}
  import os, requests
  response = requests.get(
      "https://apis.viggle.ai/v1/images/img_b16a190d-2d44-41a0-8056-ef68183c3b9e",
      headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
  )
  response.raise_for_status()
  image = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/v1/images/img_b16a190d-2d44-41a0-8056-ef68183c3b9e", {
    headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
  });
  const image = await response.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://apis.viggle.ai/v1/images/img_b16a190d-2d44-41a0-8056-ef68183c3b9e", nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY"))
  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()
  ```

  ```javascript @viggle/sdk theme={null}
  const image = await viggle.images.get("img_b16a190d-2d44-41a0-8056-ef68183c3b9e");
  console.log(image.status, image.images.map((generated) => generated.url));
  ```
</CodeGroup>

<Card title="快速入门：Viggle Image" icon="rocket" href="/zh/v1/guides/quickstart-image">
  完整的创建、轮询和下载流程。
</Card>


## OpenAPI

````yaml zh/openapi.yaml GET /v1/images/{image_id}
openapi: 3.0.3
info:
  title: Viggle API
  description: 使用 AI 生成角色动画视频。
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: 生产服务器
security:
  - bearerAuth: []
tags:
  - name: Renders
    description: 准备输入、创建渲染、观察进度并获取结果。
  - name: Credits
    description: 查询当前调用者可用的积分余额。
  - name: Characters
    description: 创建、列出、查询和删除可复用角色。type 决定是否同时提取 3D vsplat，就绪后通过导出接口获取下载链接。
  - name: Motions
    description: 创建、列出、查询和删除可复用动作，也可从官方模板导入。type 决定是否提取或生成 3D 动画，就绪后通过导出接口获取下载链接。
  - name: Videos
    description: 生成 MiniMax H3 视频（vid_）或角色动画视频（anim_），并统一查询调用者的 H3、角色动画及角色动作渲染（render_）结果。
  - name: Images
    description: Viggle Image：用 qwen 模型从文字描述生成 1–6 张 PNG（img_），可选最多 8 张参考图，并按 ID 查询结果。
paths:
  /v1/images/{image_id}:
    parameters:
      - $ref: '#/components/parameters/ImageId'
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/SourceChannel'
    get:
      tags:
        - Images
      summary: 查询图片
      description: >-
        返回图片任务的当前状态。只能查询当前 API 密钥创建的任务；ID 不存在或属于其他密钥时返回 `404 NOT_FOUND`。任务结束 24
        小时后文件被删除，任务仍为 ready，但每张图的 `url` 为 `null`。
      operationId: getImage
      responses:
        '200':
          description: 请求成功。
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '401':
          $ref: '#/components/responses/V1Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    ImageId:
      name: image_id
      in: path
      required: true
      description: POST /v1/images 返回的图片任务公开 ID，以 img_ 开头，必须由当前 API 密钥创建。
      schema:
        type: string
        minLength: 1
      example: img_b16a190d-2d44-41a0-8056-ef68183c3b9e
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      description: 可选的调用者自定义关联 ID，最长 128 字符。服务会在响应头返回实际使用的值，便于追踪和支持排查。
      schema:
        type: string
        minLength: 1
        maxLength: 128
    SourceChannel:
      name: X-Viggle-Source
      in: header
      required: false
      description: 可选来源标签，最长 128 字符，用于识别 SDK、集成、产品入口或内部工作流。
      schema:
        type: string
        minLength: 1
        maxLength: 128
  headers:
    RequestId:
      description: 用于支持排查和追踪的稳定请求 ID。
      schema:
        type: string
  schemas:
    Image:
      description: >-
        图片生成任务（img_ 前缀），创建接口与查询接口返回同一结构。状态只会向前推进：queued → processing → ready 或
        failed，不会出现 cancelled。ready 前 images 始终为空，ready 后按请求顺序列出全部 n 张。一个任务要么 n
        张全部生成，要么整体失败，不会只返回部分图片。
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - model
        - progress
        - images
        - created_at
        - completed_at
        - error
      properties:
        id:
          type: string
          minLength: 1
          description: 图片任务公开 ID，以 `img_` 开头。
        status:
          type: string
          enum:
            - queued
            - processing
            - ready
            - failed
          description: 任务状态，`ready` 和 `failed` 为终态。
        model:
          type: string
          description: 使用的模型，目前为 `qwen`。
        progress:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            已完成张数占比：queued 为 `0`，processing 为 0–99，ready 为 `100`，failed 为
            `null`。
        images:
          type: array
          description: ready 前为空；ready 后按请求顺序列出全部 n 张。
          items:
            $ref: '#/components/schemas/GeneratedImage'
        created_at:
          type: string
          format: date-time
          nullable: true
          description: 创建时间，RFC 3339。
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: 结束时间，ready 或 failed 时有值，之前为 `null`。
        error:
          type: object
          nullable: true
          description: >-
            失败原因，只在 `status` 为 `failed` 时有值。`code` 为
            `SERVICE_BUSY`（可重试：生成服务繁忙或暂时不可用，或任务 15
            分钟内未完成）、`TASK_FAILED`（可重试：其他生成或上传失败）或
            `INVALID_REQUEST`（不可重试：模型拒绝了请求，例如参考图无法使用）。
          allOf:
            - $ref: '#/components/schemas/ErrorBody'
    GeneratedImage:
      type: object
      additionalProperties: false
      required:
        - url
        - width
        - height
        - seed
      properties:
        url:
          type: string
          format: uri
          nullable: true
          description: PNG 的签名下载链接，1 小时内有效，过期后再查询一次任务即可拿到新链接。任务结束 24 小时后文件被删除，此时为 `null`。
        width:
          type: integer
          minimum: 1
          description: 实际宽度（像素）。
        height:
          type: integer
          minimum: 1
          description: 实际高度（像素）。
        seed:
          type: integer
          format: int64
          minimum: 0
          description: 这张图实际使用的 seed。
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - retryable
        - request_id
        - details
        - remediation
      properties:
        code:
          description: 恢复方法
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: 供人阅读的描述，不要解析其文本做逻辑判断。
        retryable:
          type: boolean
          description: 重试相同请求是否可能成功。
        request_id:
          type: string
          description: 用于关联 Viggle 日志与支持排查。仅当异步工作进程无法恢复原请求 ID 时为 `null`。
        details:
          type: object
          description: 补充结构化信息，可能为空。
          additionalProperties: true
        remediation:
          description: >-
            `{action, retry_after_ms}`，表示下一步操作。除非建议定时重试，否则 `retry_after_ms` 为
            `null`。
          allOf:
            - $ref: '#/components/schemas/ErrorRemediation'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          description: 草稿流程的顶层错误，包含稳定错误码、说明、重试建议、关联 ID 和错误详情。
          allOf:
            - $ref: '#/components/schemas/ErrorBody'
    ErrorCode:
      description: 草稿渲染流程的错误码集合。资源操作将相应错误映射为 ResourceError 说明的小写下划线形式。
      type: string
      enum:
        - UNAUTHENTICATED
        - INVALID_CREDENTIAL
        - FORBIDDEN
        - INVALID_REQUEST
        - INVALID_CHARACTER
        - INVALID_MOTION
        - UNSUPPORTED_MEDIA
        - CONTENT_POLICY_VIOLATION
        - UPLOAD_REQUIRED
        - UPLOAD_MISMATCH
        - UPLOAD_EXPIRED
        - DRAFT_NOT_FOUND
        - DRAFT_ALREADY_CONSUMED
        - RENDER_NOT_FOUND
        - RENDER_NOT_CANCELLABLE
        - CHARACTER_NOT_FOUND
        - MOTION_NOT_FOUND
        - MOTION_NOT_READY
        - MOTION_TEMPLATE_NOT_FOUND
        - AVATAR_NOT_FOUND
        - ANIMATION_NOT_FOUND
        - EXTRACTION_UNAVAILABLE
        - EXTRACTION_FAILED
        - IDEMPOTENCY_KEY_REUSED
        - INSUFFICIENT_CREDITS
        - RATE_LIMITED
        - SERVICE_BUSY
        - INTERNAL_ERROR
        - NOT_FOUND
        - TASK_FAILED
    ErrorRemediation:
      type: object
      additionalProperties: false
      required:
        - action
        - retry_after_ms
      properties:
        action:
          type: string
          description: 建议的下一步操作，供程序或人工读取，例如稍后重试、重新上传或修正输入。
        retry_after_ms:
          type: integer
          description: 建议重试等待的毫秒数；无需定时重试时为 null。
          nullable: true
          format: int64
          minimum: 0
  responses:
    V1Unauthorized:
      description: 请求失败，详情见错误响应。
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: 请求失败，详情见错误响应。
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: 请求失败，详情见错误响应。
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth access token
      description: 服务端 SDK 使用项目 API 密钥，Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.