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

# 查询生图任务

> 查询生图任务的当前状态。只有任务所属成员的 Public API Key 可以查询该任务。

```json 200 theme={null}
{
  "code": 200,
  "data": {
    "task_id": "task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9",
    "status": "succeeded",
    "created_at": "2026-09-12T08:30:00.000Z",
    "completed_at": "2026-09-12T08:31:42.000Z",
    "result": {
      "images": [
        {
          "asset_id": "generated/open-result/task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9-0.png",
          "url": "https://api.ch88.cn/v1/open/assets/generated%2Fopen-result%2Ftask_01K4Y8R6Z1J2X3M4N5P6Q7R8S9-0.png",
          "expires_at": "2026-09-15T08:31:42.000Z"
        }
      ]
    },
    "error": null
  },
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "type": "authentication_error",
    "message": "缺少 Public API Key"
  },
  "request_id": "req_xxx"
}
```

```json 403 theme={null}
{
  "error": {
    "code": 403,
    "type": "permission_error",
    "message": "成员或组织已停用"
  },
  "request_id": "req_xxx"
}
```

```json 404 theme={null}
{
  "error": {
    "code": 404,
    "type": "not_found_error",
    "message": "任务不存在或不属于当前成员",
    "details": {
      "upstream_code": "TASK_NOT_FOUND"
    }
  },
  "request_id": "req_xxx"
}
```

```json 429 theme={null}
{
  "error": {
    "code": 429,
    "type": "rate_limit_error",
    "message": "请求过于频繁，请稍后重试",
    "retryable": true
  },
  "request_id": "req_xxx"
}
```

```json 502 theme={null}
{
  "error": {
    "code": 502,
    "type": "upstream_error",
    "message": "上游服务暂时不可用，请稍后重试",
    "retryable": true
  },
  "request_id": "req_xxx"
}
```

```json 503 theme={null}
{
  "error": {
    "code": 503,
    "type": "service_unavailable_error",
    "message": "服务暂时不可用，请稍后重试",
    "retryable": true
  },
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
}
```


## OpenAPI

````yaml openapi/openapi.yaml GET /v1/open/tasks/{task_id}
openapi: 3.1.0
info:
  title: 灵感开放平台 API
  version: 1.0.0
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  description: >
    灵感开放平台面向外部 AI 工具和业务系统提供商品分析、A+ 策划、图片生成、图片上传、任务查询和素材下载能力。


    所有业务接口均使用 HTTPS。除公开素材地址外，请在 `Authorization` 请求头中传入成员级 Public API Key。


    所有 JSON 响应都会同步返回。成功响应统一为 `{code, data, request_id}`；错误响应统一为 `{error: {code,
    type, message, ...}, request_id}`。生图提交只返回任务编号，图片在后台继续生成，需要通过任务查询接口获取最终结果。
servers:
  - url: https://api.ch88.cn
    description: 正式环境
security:
  - PublicApiKey: []
tags:
  - name: 图片上传
    description: 上传商品图或参考图，取得可供后续接口使用的临时 URL。
  - name: AI 分析与策划
    description: 同步返回商品分析、商品图片批次策划和 A+ 页面策划结果。
  - name: 生图任务
    description: 提交异步原生图片、商品图或 A+ 图片生成任务。
  - name: 任务查询
    description: 查询异步任务状态和生成结果。
  - name: 素材下载
    description: 访问生成结果。素材地址最长保留 3 天。
paths:
  /v1/open/tasks/{task_id}:
    get:
      tags:
        - 任务查询
      summary: 查询生图任务
      description: >
        查询生图任务的当前状态。只有任务所属成员的 Public API Key 可以查询该任务。


        建议提交任务后等待 5 秒再首次查询；未完成时使用 5、8、13、20、30 秒的退避间隔，之后每 30 秒查询一次。收到终态
        `succeeded`、`failed` 或 `cancelled` 后立即停止轮询。
      operationId: getTask
      parameters:
        - name: task_id
          in: path
          required: true
          description: 生图提交响应 `data.task_id` 中的任务编号。
          schema:
            type: string
          example: task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9
      responses:
        '200':
          description: 当前任务状态。任务成功时 `result.images` 包含生成素材。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponseEnvelope'
              examples:
                processing:
                  summary: 处理中
                  value:
                    code: 200
                    data:
                      task_id: task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9
                      status: processing
                      created_at: '2026-09-12T08:30:00.000Z'
                      completed_at: null
                      result: null
                      error: null
                    request_id: req_550e8400-e29b-41d4-a716-446655440000
                succeeded:
                  summary: 已完成
                  value:
                    code: 200
                    data:
                      task_id: task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9
                      status: succeeded
                      created_at: '2026-09-12T08:30:00.000Z'
                      completed_at: '2026-09-12T08:31:42.000Z'
                      result:
                        images:
                          - asset_id: >-
                              generated/open-result/task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9-0.png
                            url: >-
                              https://api.ch88.cn/v1/open/assets/generated%2Fopen-result%2Ftask_01K4Y8R6Z1J2X3M4N5P6Q7R8S9-0.png
                            expires_at: '2026-09-15T08:31:42.000Z'
                      error: null
                    request_id: req_550e8400-e29b-41d4-a716-446655440000
                failed:
                  summary: 生成失败
                  value:
                    code: 200
                    data:
                      task_id: task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9
                      status: failed
                      created_at: '2026-09-12T08:30:00.000Z'
                      completed_at: '2026-09-12T08:30:10.000Z'
                      result: null
                      error:
                        code: GENERATION_FAILED
                        message: 图片生成失败，请修改输入后重试。
                    request_id: req_550e8400-e29b-41d4-a716-446655440000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 任务不存在，或不属于当前成员/Public API Key。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: 404
                  type: not_found_error
                  message: 任务不存在或不属于当前成员
                  details:
                    upstream_code: TASK_NOT_FOUND
                request_id: req_xxx
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailed'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    TaskResponseEnvelope:
      type: object
      required:
        - code
        - data
        - request_id
      properties:
        code:
          type: integer
          description: HTTP 状态码。
        data:
          $ref: '#/components/schemas/Task'
        request_id:
          $ref: '#/components/schemas/RequestId'
    ApiError:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          type: object
          required:
            - code
            - type
            - message
          properties:
            code:
              type: integer
              description: HTTP 状态码，例如 400、401、429、503。
            type:
              type: string
              description: 稳定错误类别，例如 `invalid_request_error`、`authentication_error`。
            message:
              type: string
              description: 中文错误说明。
            param:
              type: string
              description: 出错的请求字段。
            details:
              type: object
              additionalProperties: true
              description: 具体原因、收到的值或允许值。
            retryable:
              type: boolean
              description: 是否建议在等待后自动重试。
        request_id:
          $ref: '#/components/schemas/RequestId'
    Task:
      type: object
      required:
        - task_id
        - status
        - created_at
        - completed_at
        - result
        - error
      properties:
        task_id:
          type: string
          description: 异步任务编号。
        status:
          type: string
          enum:
            - queued
            - processing
            - succeeded
            - failed
            - cancelled
          description: 任务状态。`queued` 排队中；`processing` 处理中；其余三个值为终态。
        created_at:
          type: string
          format: date-time
          description: 任务创建时间，ISO 8601 UTC 格式。
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: 任务完成时间。未进入终态时为 `null`。
        result:
          oneOf:
            - $ref: '#/components/schemas/GenerationResult'
            - type: 'null'
          description: 任务成功后的生成结果；尚未完成或失败时通常为 `null`。
        error:
          oneOf:
            - $ref: '#/components/schemas/TaskError'
            - type: string
            - type: 'null'
          description: 任务失败信息。成功或未完成时通常为 `null`。
    RequestId:
      type: string
      description: 本次请求的诊断编号。联系平台排查问题时请提供，不要记录 Public API Key。
      example: req_550e8400-e29b-41d4-a716-446655440000
    GenerationResult:
      type: object
      required:
        - images
      properties:
        images:
          type: array
          description: 生成图片列表。
          items:
            $ref: '#/components/schemas/GeneratedImage'
    TaskError:
      type: object
      properties:
        code:
          type: string
          description: 任务失败错误码。
        message:
          type: string
          description: 可向开发者展示的错误说明。
    GeneratedImage:
      type: object
      required:
        - asset_id
        - url
        - expires_at
      properties:
        asset_id:
          type: string
          description: 生成素材标识。自行拼接下载 URL 时需要进行 URL 编码。
        url:
          type: string
          format: uri
          description: 生成图片的临时完整访问地址，可在有效期内直接通过浏览器访问。
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: 图片预计过期时间。缓存成功时最长为 3 天；为 `null` 时应尽快下载。
  responses:
    Unauthorized:
      description: Public API Key 缺失、错误、过期或已删除。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            missing:
              value:
                error:
                  code: 401
                  type: authentication_error
                  message: 缺少 Public API Key
                request_id: req_xxx
            invalid:
              value:
                error:
                  code: 401
                  type: authentication_error
                  message: Public API Key 无效、已过期或已删除
                request_id: req_xxx
    Forbidden:
      description: Public API Key 所属成员或组织已停用。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: 403
              type: permission_error
              message: 成员或组织已停用
            request_id: req_xxx
    RateLimited:
      description: 请求触发平台或上游动态限流。平台当前未对外承诺固定 QPS 或并发数。
      headers:
        Retry-After:
          description: 如果响应包含该请求头，请至少等待指定秒数后重试。
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: 429
              type: rate_limit_error
              message: 请求过于频繁，请稍后重试
              retryable: true
            request_id: req_xxx
    UpstreamFailed:
      description: 上游服务不可用、返回格式异常或生成失败。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: 502
              type: upstream_error
              message: 上游服务暂时不可用，请稍后重试
              retryable: true
            request_id: req_xxx
    ServiceUnavailable:
      description: 灵感开放平台服务或所需存储、认证能力暂时不可用。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: 503
              type: service_unavailable_error
              message: 服务暂时不可用，请稍后重试
              retryable: true
            request_id: req_550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    PublicApiKey:
      type: http
      scheme: bearer
      bearerFormat: Linggan Public API Key
      description: >
        成员级 Public API Key。请填写完整密钥，Mintlify Playground 会自动以 `Authorization:
        Bearer <PUBLIC_API_KEY>` 发送。完整明文只在管理后台创建成功时显示一次。

````

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