> ## 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.

# 提交商品图片生成任务

> 提交一项商品图片生成任务。接口只负责接受任务，不会等待图片生成完成。

```json 200 theme={null}
{
  "code": 200,
  "data": {
    "status": "submitted",
    "task_id": "task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9"
  },
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "type": "invalid_request_error",
    "message": "请至少提供 1 张产品图"
  },
  "request_id": "req_xxx"
}
```

```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 409 theme={null}
{
  "error": {
    "code": 409,
    "type": "conflict_error",
    "message": "成员未分配有效上游密钥"
  },
  "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 POST /v1/open/product-images/generations
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/product-images/generations:
    post:
      tags:
        - 生图任务
      summary: 提交商品图片生成任务
      description: |
        提交一项商品图片生成任务。接口只负责接受任务，不会等待图片生成完成。

        相同成员在 10 分钟内提交完全相同的生成请求时，平台会复用已完成响应，或在首个请求仍处理中时返回冲突错误。
      operationId: createProductImageGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductImageGenerationRequest'
            examples:
              mainImage:
                summary: 生成方形商品主图
                value:
                  prompt: 生成一张简洁高级的护肤品电商主图，产品居中，背景干净，保留真实包装细节。
                  image_urls:
                    - >-
                      https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2Fexample-front.png
                  product_info:
                    name: 保湿精华液
                    sellingPoints: 清爽肤感，适合日常保湿
                    platform: Amazon
                  size: '1:1'
                  resolution: 1k
                  output_language: zh-cn
      responses:
        '200':
          description: >
            ### 查询任务结果


            任务提交成功后返回 `data.task_id`。请保存该任务编号，并通过 `GET /v1/open/tasks/{task_id}`
            轮询任务状态，详见[查询生图任务](/api-reference/endpoints/get-task)。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationSubmissionResponseEnvelope'
              example:
                code: 200
                data:
                  status: submitted
                  task_id: task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9
                request_id: req_550e8400-e29b-41d4-a716-446655440000
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailed'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    ProductImageGenerationRequest:
      type: object
      additionalProperties: false
      required:
        - prompt
        - image_urls
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 3000
          description: 生图要求。建议写明主体、用途、场景、构图、视觉风格、文字语言和禁止项。
        image_urls:
          type: array
          minItems: 1
          maxItems: 15
          description: 商品图或参考图 URL。当前商品生图接口至少需要 1 张、最多 15 张。
          items:
            type: string
            format: uri
        product_info:
          $ref: '#/components/schemas/ProductInfo'
        size:
          type: string
          enum:
            - auto
            - '1:1'
            - '3:2'
            - '2:3'
            - '4:3'
            - '3:4'
            - '5:4'
            - '4:5'
            - '16:9'
            - '9:16'
            - '2:1'
            - '1:2'
            - '3:1'
            - '1:3'
            - '21:9'
            - '9:21'
          default: auto
          description: 模型生成画布比例。除 `auto` 外支持 15 个固定比例；1K、2K、4K 均支持这些比例。
        resolution:
          type: string
          enum:
            - 1k
            - 2k
            - 4k
          default: 1k
          description: 输出分辨率档位。更高分辨率通常需要更长处理时间。
        output_language:
          type: string
          default: zh-cn
          description: |
            图片中文字的目标语言。枚举值与语言对应关系：

            - `no-text`：无文字（纯视觉）
            - `thai`：泰语
            - `indonesian`：印度尼西亚语
            - `vietnamese`：越南语
            - `malay`：马来语
            - `zh-cn`：简体中文
            - `english`：英语
            - `japanese`：日语
            - `korean`：韩语
            - `filipino`：菲律宾语
            - `zh-tw`：繁体中文
            - `french`：法语
            - `spanish`：西班牙语
            - `german`：德语
            - `italian`：意大利语
            - `portuguese`：葡萄牙语
            - `russian`：俄语
            - `arabic`：阿拉伯语
          enum:
            - no-text
            - thai
            - indonesian
            - vietnamese
            - malay
            - zh-cn
            - english
            - japanese
            - korean
            - filipino
            - zh-tw
            - french
            - spanish
            - german
            - italian
            - portuguese
            - russian
            - arabic
    GenerationSubmissionResponseEnvelope:
      type: object
      required:
        - code
        - data
        - request_id
      properties:
        code:
          type: integer
          description: HTTP 状态码。任务接受时为 200。
        data:
          $ref: '#/components/schemas/GenerationSubmissionData'
        request_id:
          $ref: '#/components/schemas/RequestId'
    ProductInfo:
      type: object
      additionalProperties: false
      description: 已知的结构化商品信息。所有数据应来自客户资料或可确认事实。
      properties:
        name:
          type: string
          description: 商品名称。
        sellingPoints:
          type: string
          description: 可确认的核心卖点。
        usage:
          type: string
          description: 使用方式或适用场景。
        salesRegion:
          type: string
          description: 销售国家或地区。
        platform:
          type: string
          description: 销售平台。
        visualStyle:
          type: string
          description: 期望的视觉风格。
        dimensions:
          $ref: '#/components/schemas/ProductDimensions'
        extra:
          type: string
          description: 其他需要在生图中考虑的事实或约束。
    GenerationSubmissionData:
      type: object
      required:
        - status
        - task_id
      properties:
        status:
          type: string
          description: 任务提交状态，成功时为 `submitted`。
        task_id:
          type: string
          description: 异步任务编号。请保存并传给任务查询接口。
    RequestId:
      type: string
      description: 本次请求的诊断编号。联系平台排查问题时请提供，不要记录 Public API Key。
      example: req_550e8400-e29b-41d4-a716-446655440000
    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'
    ProductDimensions:
      type: object
      required:
        - unit
      properties:
        length:
          type: string
          description: 商品长度，仅填写数值。
        width:
          type: string
          description: 商品宽度，仅填写数值。
        height:
          type: string
          description: 商品高度，仅填写数值。
        unit:
          type: string
          enum:
            - cm
            - in
          description: 尺寸单位，`cm` 为厘米，`in` 为英寸。
  responses:
    ValidationFailed:
      description: >-
        请求体格式错误、缺少必填字段或字段值不受支持。`error.code` 为 HTTP 状态码，具体字段信息放在 `param` 和
        `details`。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: 400
              type: invalid_request_error
              message: 请至少提供 1 张产品图
            request_id: req_xxx
    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
    Conflict:
      description: 成员未分配有效上游密钥，或相同生成请求仍在处理中。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          examples:
            credential:
              value:
                error:
                  code: 409
                  type: conflict_error
                  message: 成员未分配有效上游密钥
                request_id: req_xxx
            duplicate:
              value:
                error:
                  code: 409
                  type: conflict_error
                  message: 相同生成请求正在处理中，请勿重复提交
                  retryable: true
                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.