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

# 提交 A+ 图片生成任务

> 为一个 A+ 模块提交图片生成任务。`module_key` 和 `image_urls` 必填；默认模型为 `gpt-image-2`，默认分辨率为 `1k`。

```json 200 theme={null}
{
  "code": 200,
  "data": {
    "status": "submitted",
    "task_id": "task_01K4Y9A7B8C9D0E1F2G3H4J5K6"
  },
  "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/aplus/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/aplus/generations:
    post:
      tags:
        - 生图任务
      summary: 提交 A+ 图片生成任务
      description: >
        为一个 A+ 模块提交图片生成任务。`module_key` 和 `image_urls` 必填；默认模型为
        `gpt-image-2`，默认分辨率为 `1k`。


        `target_size` 决定最终 A+ 交付版式，平台会自动选择兼容的模型生成画布。
      operationId: createAplusGeneration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AplusGenerationRequest'
            examples:
              coreModule:
                summary: 生成核心卖点模块
                value:
                  module_key: core
                  target_size: 970x600
                  model: gpt-image-2
                  product_brief: 一款滴管瓶装保湿精华液，面向日常补水保湿需求。
                  module_note: 突出清爽质地，不使用医疗或夸大功效表述。
                  platform: Amazon
                  market: US
                  language: zh-CN
                  resolution: 1k
                  image_urls:
                    - >-
                      https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2Fexample-front.png
                  plan_prompt: 以产品瓶身为中心，使用水感背景和简洁的信息分区。
                  negative_prompt: 不添加未经证实的认证、奖项或功效数据。
                  series_style_guide: 浅蓝与白色体系，柔和自然光，所有模块保持一致。
      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_01K4Y9A7B8C9D0E1F2G3H4J5K6
                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:
    AplusGenerationRequest:
      type: object
      additionalProperties: false
      required:
        - module_key
        - image_urls
      properties:
        module_key:
          $ref: '#/components/schemas/AplusModuleKey'
        target_size:
          type: string
          enum:
            - 1464x600
            - 970x600
            - 970x300
            - 600x450
            - 463x625
            - 220x220
            - 150x300
          description: A+ 最终交付版式尺寸。省略时使用所选模块的默认尺寸。
        generation_size:
          type: string
          description: 可选的模型原生生成比例。通常无需填写；如果填写，必须与 `target_size` 和 `model` 的平台映射一致。
          example: '3:2'
        model:
          type: string
          enum:
            - gpt-image-2
            - nano-banana-2-lite
            - nano-banana-2
            - nano-banana-pro
          default: gpt-image-2
          description: A+ 生图模型。不同模型支持的图片数量和分辨率不同。
        product_brief:
          type: string
          maxLength: 2000
          description: 商品简报。未传入 `plan_prompt` 时强烈建议提供。
        module_note:
          type: string
          description: 当前模块的补充要求。
        platform:
          type: string
          default: Amazon
          description: 目标电商平台。
        market:
          type: string
          description: 目标市场或国家。
        language:
          type: string
          default: zh-CN
          description: 图片文案语言；使用 `no-text` 可要求纯视觉画面。
        resolution:
          type: string
          enum:
            - 0.5k
            - 1k
            - 2k
            - 4k
          default: 1k
          description: 输出分辨率。`0.5k` 仅部分模型支持。
        image_urls:
          type: array
          minItems: 1
          maxItems: 15
          description: 商品图 URL。`gpt-image-2` 最多 15 张，三个 Banana 模型最多 14 张。
          items:
            type: string
            format: uri
        plan_prompt:
          type: string
          description: A+ 策划接口返回的 `recommended_prompt`，或客户编辑后的模块提示词。
        negative_prompt:
          type: string
          description: 不希望图片中出现的内容和表现方式。
        series_style_guide:
          type: string
          description: A+ 策划接口返回的 `global_style`，用于保持多模块视觉一致。
    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'
    AplusModuleKey:
      type: string
      description: |
        A+ 模块标识。枚举值与模块名称对应关系：

        - `hero`：首屏主视觉
        - `core`：核心卖点图
        - `usage`：使用场景图
        - `angles`：多角度图
        - `mood`：场景氛围图
        - `detail`：商品细节图
        - `brand`：品牌故事图
        - `size`：尺寸/容量/尺码图
        - `compare`：效果对比图
        - `specs`：详细规格/参数表
        - `process`：工艺制作图
        - `accessories`：配件/赠品图
        - `series`：系列展示图
        - `ingredients`：商品成分图
        - `care`：售后保障图
        - `tips`：使用建议图
      enum:
        - hero
        - core
        - usage
        - angles
        - mood
        - detail
        - brand
        - size
        - compare
        - specs
        - process
        - accessories
        - series
        - ingredients
        - care
        - tips
    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'
  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.