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

# 商品 AI 分析

> 根据 1 至 15 张商品图片同步返回结构化商品分析。接口会识别商品定位、目标人群、核心卖点、使用场景、类目、可确认属性、A+ 表达重点、合规注意事项和待确认信息。

```json 200 theme={null}
{
  "code": 200,
  "data": {
    "analysis": {
      "productName": "保湿精华液",
      "positioning": "面向日常保湿需求的轻盈型面部精华",
      "targetAudience": "关注补水保湿和清爽肤感的成年消费者",
      "coreSellingPoint": "清爽保湿，适合日常护肤搭配",
      "sellingPointDescription": "以产品图片中可确认的信息为基础，突出日常补水和易搭配的使用定位。",
      "useScenarios": [
        "早间护肤",
        "晚间护肤"
      ],
      "category": {
        "general": "美妆个护",
        "specific": "面部精华",
        "searchKeywords": [
          "保湿精华",
          "补水精华",
          "面部护理"
        ]
      },
      "attributes": [
        {
          "label": "包装形式",
          "value": "滴管瓶",
          "evidence": "visible"
        }
      ],
      "aplusFocus": [
        "突出产品质地与使用步骤",
        "展示日常护肤场景"
      ],
      "complianceNotes": [
        "不使用未经证实的功效或医疗表述"
      ],
      "uncertainClaims": [
        "具体容量需根据包装实物确认"
      ]
    },
    "formattedText": "产品名称：保湿精华液\n产品定位：面向日常保湿需求的轻盈型面部精华\n目标人群：关注补水保湿和清爽肤感的成年消费者",
    "output_text": "产品名称：保湿精华液\n产品定位：面向日常保湿需求的轻盈型面部精华\n目标人群：关注补水保湿和清爽肤感的成年消费者"
  },
  "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-analysis
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-analysis:
    post:
      tags:
        - AI 分析与策划
      summary: 商品 AI 分析
      description: >
        根据 1 至 15 张商品图片同步返回结构化商品分析。接口会识别商品定位、目标人群、核心卖点、使用场景、类目、可确认属性、A+
        表达重点、合规注意事项和待确认信息。


        该接口为同步接口，不需要轮询。AI 分析可能需要数十秒，客户端超时时间建议设置为至少 120 秒。
      operationId: createProductAnalysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductAnalysisRequest'
            examples:
              skincare:
                summary: 分析护肤品
                value:
                  product_name: 保湿精华液
                  image_urls:
                    - >-
                      https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2Fexample-front.png
                    - >-
                      https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2Fexample-back.png
      responses:
        '200':
          description: 商品分析完成。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductAnalysisResponseEnvelope'
              examples:
                success:
                  summary: 商品分析结果
                  value:
                    code: 200
                    data:
                      analysis:
                        productName: 保湿精华液
                        positioning: 面向日常保湿需求的轻盈型面部精华
                        targetAudience: 关注补水保湿和清爽肤感的成年消费者
                        coreSellingPoint: 清爽保湿，适合日常护肤搭配
                        sellingPointDescription: 以产品图片中可确认的信息为基础，突出日常补水和易搭配的使用定位。
                        useScenarios:
                          - 早间护肤
                          - 晚间护肤
                        category:
                          general: 美妆个护
                          specific: 面部精华
                          searchKeywords:
                            - 保湿精华
                            - 补水精华
                            - 面部护理
                        attributes:
                          - label: 包装形式
                            value: 滴管瓶
                            evidence: visible
                        aplusFocus:
                          - 突出产品质地与使用步骤
                          - 展示日常护肤场景
                        complianceNotes:
                          - 不使用未经证实的功效或医疗表述
                        uncertainClaims:
                          - 具体容量需根据包装实物确认
                      formattedText: |-
                        产品名称：保湿精华液
                        产品定位：面向日常保湿需求的轻盈型面部精华
                        目标人群：关注补水保湿和清爽肤感的成年消费者
                      output_text: |-
                        产品名称：保湿精华液
                        产品定位：面向日常保湿需求的轻盈型面部精华
                        目标人群：关注补水保湿和清爽肤感的成年消费者
                    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:
    ProductAnalysisRequest:
      type: object
      additionalProperties: false
      required:
        - image_urls
      properties:
        product_name:
          type: string
          maxLength: 200
          description: 已知的商品名称，用于辅助识别；不确定时可以省略。
          example: 保湿精华液
        image_urls:
          type: array
          minItems: 1
          maxItems: 15
          description: 商品图片 URL，至少 1 张、最多 15 张。建议包含正面、背面和关键细节。
          items:
            type: string
            format: uri
    ProductAnalysisResponseEnvelope:
      type: object
      required:
        - code
        - data
        - request_id
      properties:
        code:
          type: integer
          description: HTTP 状态码。
        data:
          $ref: '#/components/schemas/ProductAnalysisResponse'
        request_id:
          $ref: '#/components/schemas/RequestId'
    ProductAnalysisResponse:
      type: object
      required:
        - analysis
        - formattedText
        - output_text
      properties:
        analysis:
          $ref: '#/components/schemas/ProductAnalysis'
        formattedText:
          type: string
          description: 适合直接展示或继续编辑的中文商品简报。
        output_text:
          type: string
          description: 与 `formattedText` 相同的兼容字段。
    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'
    ProductAnalysis:
      type: object
      required:
        - productName
        - positioning
        - targetAudience
        - coreSellingPoint
        - sellingPointDescription
        - useScenarios
        - category
        - attributes
        - aplusFocus
        - complianceNotes
        - uncertainClaims
      properties:
        productName:
          type: string
          description: AI 识别或请求中提供的商品名称。
        positioning:
          type: string
          description: 商品的市场定位与核心用途概述。
        targetAudience:
          type: string
          description: 适合的目标消费人群。
        coreSellingPoint:
          type: string
          description: 最核心且有依据的商品卖点。
        sellingPointDescription:
          type: string
          description: 对核心卖点的展开说明。
        useScenarios:
          type: array
          maxItems: 8
          description: 商品适用的典型场景。
          items:
            type: string
        category:
          $ref: '#/components/schemas/ProductCategory'
        attributes:
          type: array
          maxItems: 10
          description: 从图片、客户输入或合理推断中得到的商品属性。
          items:
            $ref: '#/components/schemas/ProductAttribute'
        aplusFocus:
          type: array
          maxItems: 6
          description: 适合在 A+ 页面重点表达的内容。
          items:
            type: string
        complianceNotes:
          type: array
          maxItems: 8
          description: 宣传和生图时需要遵守的合规注意事项。
          items:
            type: string
        uncertainClaims:
          type: array
          maxItems: 10
          description: 无法从现有材料确认、需要客户补充核实的信息。
          items:
            type: string
    ProductCategory:
      type: object
      required:
        - general
        - specific
        - searchKeywords
      properties:
        general:
          type: string
          description: 商品所属一级类目。
        specific:
          type: string
          description: 商品所属细分类目。
        searchKeywords:
          type: array
          maxItems: 5
          description: 适合检索和内容策划使用的类目关键词。
          items:
            type: string
    ProductAttribute:
      type: object
      required:
        - label
        - value
        - evidence
      properties:
        label:
          type: string
          description: 属性名称，例如包装形式或可见材质。
        value:
          type: string
          description: 属性值或说明。
        evidence:
          type: string
          enum:
            - visible
            - provided
            - inferred
          description: 信息依据。`visible` 为图片可见，`provided` 为客户提供，`inferred` 为 AI 合理推断。
  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.