> ## 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+ AI 策划

> 根据商品图片、商品说明和选定模块，同步生成 A+ 页面策划。返回每个模块的标题、策划简报、推荐生图提示词以及统一视觉风格。

```json 200 theme={null}
{
  "code": 200,
  "data": {
    "modules": [
      {
        "module_key": "hero",
        "title": "清爽保湿，从每日一滴开始",
        "brief": "以产品瓶身为视觉中心，建立干净、轻盈的首屏氛围。",
        "recommended_prompt": "展示真实产品瓶身，使用清透水感背景与柔和自然光，保留标题安全区。"
      },
      {
        "module_key": "core",
        "title": "日常保湿核心卖点",
        "brief": "用简洁信息层级解释产品的日常使用价值。",
        "recommended_prompt": "以产品特写搭配清晰信息分区，不添加未经证实的功效表述。"
      }
    ],
    "global_style": "清透、克制、明亮，统一使用浅蓝与白色视觉体系。",
    "notes": [
      "所有产品事实以客户提供资料和可见包装信息为准"
    ]
  },
  "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/plans
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/plans:
    post:
      tags:
        - AI 分析与策划
      summary: A+ AI 策划
      description: |
        根据商品图片、商品说明和选定模块，同步生成 A+ 页面策划。返回每个模块的标题、策划简报、推荐生图提示词以及统一视觉风格。

        该接口为同步接口，不需要轮询。客户端超时时间建议设置为至少 120 秒。
      operationId: createAplusPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AplusPlanRequest'
            examples:
              amazon:
                summary: 生成 Amazon A+ 策划
                value:
                  product_description: 一款滴管瓶装保湿精华液，主打清爽日常保湿。
                  image_urls:
                    - >-
                      https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2Fexample-front.png
                  modules:
                    - hero
                    - core
                    - usage
                  platform: Amazon
                  market: US
                  language: zh-CN
      responses:
        '200':
          description: A+ 策划完成。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AplusPlanResponseEnvelope'
              examples:
                success:
                  summary: A+ 策划结果
                  value:
                    code: 200
                    data:
                      modules:
                        - module_key: hero
                          title: 清爽保湿，从每日一滴开始
                          brief: 以产品瓶身为视觉中心，建立干净、轻盈的首屏氛围。
                          recommended_prompt: 展示真实产品瓶身，使用清透水感背景与柔和自然光，保留标题安全区。
                        - module_key: core
                          title: 日常保湿核心卖点
                          brief: 用简洁信息层级解释产品的日常使用价值。
                          recommended_prompt: 以产品特写搭配清晰信息分区，不添加未经证实的功效表述。
                      global_style: 清透、克制、明亮，统一使用浅蓝与白色视觉体系。
                      notes:
                        - 所有产品事实以客户提供资料和可见包装信息为准
                    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/CredentialUnavailable'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamFailed'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    AplusPlanRequest:
      type: object
      additionalProperties: false
      required:
        - image_urls
        - modules
      properties:
        product_description:
          type: string
          maxLength: 2000
          description: 商品简报或商品分析结果整理后的文本。强烈建议提供，以减少 AI 对事实的推断。
        image_urls:
          type: array
          minItems: 1
          maxItems: 15
          description: 商品图片 URL。`gpt-image-2` 最多 15 张，三个 Banana 模型最多 14 张。
          items:
            type: string
            format: uri
        model:
          type: string
          enum:
            - gpt-image-2
            - nano-banana-2-lite
            - nano-banana-2
            - nano-banana-pro
          default: gpt-image-2
          description: 后续执行 A+ 生图的模型，用于按模型校验参考图数量。
        modules:
          type: array
          minItems: 1
          maxItems: 16
          uniqueItems: true
          description: 需要策划的 A+ 模块标识。
          items:
            $ref: '#/components/schemas/AplusModuleKey'
        platform:
          type: string
          maxLength: 100
          default: Amazon
          description: 销售平台，例如 `Amazon`。
        market:
          type: string
          maxLength: 100
          description: 目标市场，例如 `US`、`美国`。
        language:
          type: string
          maxLength: 50
          default: zh-CN
          description: 策划内容和图片文案使用的语言。
    AplusPlanResponseEnvelope:
      type: object
      required:
        - code
        - data
        - request_id
      properties:
        code:
          type: integer
          description: HTTP 状态码。
        data:
          $ref: '#/components/schemas/AplusPlanResult'
        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
    AplusPlanResult:
      type: object
      required:
        - modules
        - global_style
        - notes
      properties:
        modules:
          type: array
          description: 按请求模块生成的策划列表。
          items:
            $ref: '#/components/schemas/AplusModulePlan'
        global_style:
          type: string
          description: 所有 A+ 模块应统一遵循的视觉风格说明。
        notes:
          type: array
          description: 策划执行时需要额外注意的事实、合规或一致性说明。
          items:
            type: string
    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'
    AplusModulePlan:
      type: object
      required:
        - module_key
        - title
        - brief
        - recommended_prompt
      properties:
        module_key:
          $ref: '#/components/schemas/AplusModuleKey'
        title:
          type: string
          description: 模块策划标题。
        brief:
          type: string
          description: 模块的内容目标、版式重点和表达说明。
        recommended_prompt:
          type: string
          description: 可以直接传入 A+ 生图接口 `plan_prompt` 的推荐提示词。
  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
    CredentialUnavailable:
      description: 当前成员未分配有效的上游密钥，或上游密钥暂时无法解密。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            error:
              code: 409
              type: conflict_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.