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

# 上传图片

> 上传一张商品图、参考图或其他生图输入图片。支持 PNG、JPEG、WebP、GIF 和 AVIF。文件上限按目标模型校验：`gpt-image-2` 为 20 MB，`nano-banana-2-lite` 和 `nano-banana-2` 为 10 MB，`nano-banana-pro` 为 30 MB。

```json 201 theme={null}
{
  "code": 201,
  "data": {
    "id": "generated/open-upload/550e8400-e29b-41d4-a716-446655440000.png",
    "url": "https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2F550e8400-e29b-41d4-a716-446655440000.png",
    "expiresAt": "2026-09-15T08:30:00.000Z"
  },
  "request_id": "req_550e8400-e29b-41d4-a716-446655440000"
}
```

```json 400 theme={null}
{
  "error": {
    "code": 400,
    "type": "invalid_request_error",
    "message": "不支持或损坏的图片文件",
    "details": {
      "upstream_code": "INVALID_IMAGE_FILE"
    }
  },
  "request_id": "req_xxx"
}
```

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

```json 413 theme={null}
{
  "error": {
    "code": 413,
    "type": "invalid_request_error",
    "message": "gpt-image-2 图片大小必须在 1 字节到 20971520 字节之间",
    "details": {
      "upstream_code": "FILE_TOO_LARGE"
    }
  },
  "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/uploads/images
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/uploads/images:
    post:
      tags:
        - 图片上传
      summary: 上传图片
      description: >
        上传一张商品图、参考图或其他生图输入图片。支持 PNG、JPEG、WebP、GIF 和
        AVIF。文件上限按目标模型校验：`gpt-image-2` 为 20 MB，`nano-banana-2-lite` 和
        `nano-banana-2` 为 10 MB，`nano-banana-pro` 为 30 MB。


        返回的 `url` 可以直接用于后续接口的 `image_urls`，也可以在有效期内通过浏览器直接访问。图片最长保留 3 天，到期后可能返回
        404，请勿将其作为永久存储地址。
      operationId: uploadImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  contentMediaType: image/png
                  description: 图片文件。支持 PNG、JPEG、WebP、GIF、AVIF，实际大小上限由 `model` 决定。
                model:
                  type: string
                  enum:
                    - gpt-image-2
                    - nano-banana-2-lite
                    - nano-banana-2
                    - nano-banana-pro
                  default: gpt-image-2
                  description: 目标生图模型。省略时按 `gpt-image-2` 的 20 MB 上限校验。
      responses:
        '201':
          description: 图片上传成功。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedImageResponse'
              examples:
                success:
                  summary: 上传成功
                  value:
                    code: 201
                    data:
                      id: >-
                        generated/open-upload/550e8400-e29b-41d4-a716-446655440000.png
                      url: >-
                        https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2F550e8400-e29b-41d4-a716-446655440000.png
                      expiresAt: '2026-09-15T08:30:00.000Z'
                    request_id: req_550e8400-e29b-41d4-a716-446655440000
        '400':
          description: 缺少文件，或文件格式不支持、文件已损坏。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: 400
                  type: invalid_request_error
                  message: 不支持或损坏的图片文件
                  details:
                    upstream_code: INVALID_IMAGE_FILE
                request_id: req_xxx
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          description: 文件超过所选模型的大小上限。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                error:
                  code: 413
                  type: invalid_request_error
                  message: gpt-image-2 图片大小必须在 1 字节到 20971520 字节之间
                  details:
                    upstream_code: FILE_TOO_LARGE
                request_id: req_xxx
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    UploadedImageResponse:
      type: object
      required:
        - code
        - data
        - request_id
      properties:
        code:
          type: integer
          description: HTTP 状态码。成功上传时为 201
          example: 201
        data:
          $ref: '#/components/schemas/UploadedImage'
        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'
    UploadedImage:
      type: object
      required:
        - id
        - url
        - expiresAt
      properties:
        id:
          type: string
          description: R2 中的临时图片资源标识。通常不需要自行使用该值。
          example: generated/open-upload/550e8400-e29b-41d4-a716-446655440000.png
        url:
          type: string
          format: uri
          description: 图片临时公开访问地址，可直接传入后续接口的 `image_urls`，最长有效 3 天。
        expiresAt:
          type: string
          format: date-time
          description: 图片预计过期时间，ISO 8601 UTC 格式。到期后图片可能被自动清理。
    RequestId:
      type: string
      description: 本次请求的诊断编号。联系平台排查问题时请提供，不要记录 Public API Key。
      example: req_550e8400-e29b-41d4-a716-446655440000
  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
    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.