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

# 提交原生图片生成任务

> 根据调用方提供的提示词、参考图片、比例和分辨率直接提交图片生成任务。当前生图模型为 image-2。

```json 200 theme={null}
{
  "code": 200,
  "data": {
    "status": "submitted",
    "task_id": "task_01K4Y7N5X6A7B8C9D0E1F2G3H4"
  },
  "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 413 theme={null}
{
  "error": {
    "code": 413,
    "type": "invalid_request_error",
    "message": "请求体最大支持 32 MB",
    "param": "body"
  },
  "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/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/images/generations:
    post:
      tags:
        - 生图任务
      summary: 提交原生图片生成任务
      description: >
        根据调用方提供的提示词、参考图片、比例和分辨率直接提交图片生成任务。当前生图模型为 image-2。


        平台不会改写、补充或拼接 `prompt`。`image_urls` 可以省略；省略时为文生图，传入时为图生图。参考图支持公网 URL 和
        Base64 Data URI 混合传入。
      operationId: createNativeImageGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NativeImageGenerationRequest'
            examples:
              textToImage:
                summary: 文生图
                value:
                  prompt: 一只橘猫坐在窗台上看夕阳，水彩画风格。
                  size: '16:9'
                  resolution: 2k
              imageToImage:
                summary: URL 与 Base64 参考图混合输入
                value:
                  prompt: 保持商品外观不变，改为浅色摄影棚背景和柔和侧光。
                  image_urls:
                    - >-
                      https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2Fexample-front.png
                    - data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
                  size: '1:1'
                  resolution: 1k
      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_01K4Y7N5X6A7B8C9D0E1F2G3H4
                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'
        '413':
          description: 请求体或 Base64 图片超过大小上限。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: 413
                  type: invalid_request_error
                  message: 请求体最大支持 32 MB
                  param: body
                request_id: req_xxx
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailed'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    NativeImageGenerationRequest:
      type: object
      additionalProperties: false
      required:
        - prompt
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 32000
          description: 图片生成提示词。
        image_urls:
          type: array
          maxItems: 15
          description: >
            参考图片，最多 15 张。每项可以是公网可访问的 HTTP(S) URL，也可以是
            `data:image/png;base64,...` 格式的 Base64 Data URI，两种形式可以混合传入。


            省略或传空数组时为文生图。Base64 图片单张解码后最大 20 MB，包含 JSON 在内的整个请求体最大 32
            MB；多张或大图建议先调用图片上传接口再传 URL。
          items:
            type: string
            description: HTTP(S) URL 或图片 Base64 Data URI。
        size:
          type: string
          default: '1:1'
          description: |
            图像生成的比例。支持以下比例，也可传入 `auto` 由服务端自动选择合适比例：

            | `size` | 类型 |
            | --- | --- |
            | `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` | 竖图 |

            也支持直接传入像素尺寸，例如 `1881x836` / `887x1774`。

            **注意：**当 `size` 传入 `auto` 时，默认比例为 `1:1`。
        resolution:
          type: string
          enum:
            - 1k
            - 2k
            - 4k
          default: 1k
          description: >
            输出分辨率档位。


            可选值：`1k` / `2k` / `4k`


            `size × resolution` 对应的实际像素：


            | `size` | `1k` | `2k` | `4k` |

            | --- | --- | --- | --- |

            | `1:1` | `1024×1024` / `1254×1254` | `2048×2048` | **`2880×2880`**
            |

            | `3:2` | `1536×1024` | `2048×1360` | **`3520×2336`** |

            | `2:3` | `1024×1536` | `1360×2048` | **`2336×3520`** |

            | `4:3` | `1024×768` | `2048×1536` | **`3312×2480`** |

            | `3:4` | `768×1024` | `1536×2048` | **`2480×3312`** |

            | `5:4` | `1280×1024` / `1448×1086` | `2560×2048` | **`3216×2576`**
            |

            | `4:5` | `1024×1280` / `1122×1402` | `2048×2560` | **`2576×3216`**
            |

            | `16:9` | `1536×864` / `1672×941` | `2048×1152` | **`3840×2160`** |

            | `9:16` | `864×1536` / `941×1672` | `1152×2048` | **`2160×3840`** |

            | `2:1` | `2048×1024` / `1774×887` | `2688×1344` | **`3840×1920`** |

            | `1:2` | `1024×2048` / `887×1774` | `1344×2688` | **`1920×3840`** |

            | `3:1` | `1881×836` / `1536×512` | `3072×1024` | **`3840×1280`** |

            | `1:3` | `887×1774` / `512×1536` | `1024×3072` | **`1280×3840`** |

            | `21:9` | `2016×864` / `1915×821` | `2688×1152` | **`3840×1648`** |

            | `9:21` | `864×2016` / `821×1915` | `1152×2688` | **`1648×3840`** |


            **注意：**4K 支持上述 15 个比例；也可以直接通过 `size` 传入表格中的像素尺寸。
        'n':
          type: integer
          minimum: 1
          maximum: 1
          default: 1
          description: |
            生成图片张数。

            取值：`1`。省略时默认为 `1`。

            **注意：**只能传入纯数字 `1`，不要加引号。当前不支持其他数字。
    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'
    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'
    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
  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.