# AI 生图平台白底图接口文档

> 用途：AI 生图平台输入 `SKU` 后，直接从素材库获取该 `SKU` 对应的白底图。
> 当前主域名：`https://sc.jiansun.vip`
> 旧域名：`https://3d.yydd.ai`，保留兼容并跳转到新域名

## 1. 基础信息

- **接口基地址**：`https://sc.jiansun.vip/api/external/`
- **鉴权方式**：请求头 `X-API-Key`
- **返回格式**：`application/json`
- **适用范围**：仅适用于 `标准模型` 类型素材

## 2. 接口说明

### 2.1 按 SKU 查询白底图

**请求**

```http
GET /api/external/standard-model-white-background?sku={SKU}
X-API-Key: 5073534d7a59babbc45397a8eac5943b
```

**请求参数**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `sku` | string | 是 | SKU 名称。接口按大小写不敏感查询。 |

**请求头**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `X-API-Key` | string | 是 | 外部接口访问密钥 |

## 3. 成功响应

**响应示例**

```json
{
  "success": true,
  "data": {
    "sku": "text001452",
    "materialId": "484bd047-c956-48cf-a0f4-401f696aef8d",
    "productModel": "TEXT0014",
    "whiteBackground": {
      "fixed": [
        {
          "key": "leftFront45",
          "label": "左前45°",
          "fileName": "左前45°.png",
          "fileSize": 68,
          "downloadUrl": "https://3d.yydd.ai/api/external/download?token=xxx"
        },
        {
          "key": "rightFront45",
          "label": "右前45°",
          "fileName": "右前45°.png",
          "fileSize": 68,
          "downloadUrl": "https://3d.yydd.ai/api/external/download?token=xxx"
        }
      ],
      "other": [
        {
          "key": "other",
          "label": "其他图片",
          "fileName": "01-other-1.png",
          "fileSize": 68,
          "downloadUrl": "https://3d.yydd.ai/api/external/download?token=xxx"
        }
      ]
    },
    "downloadUrls": {
      "zip": "https://3d.yydd.ai/api/external/download?token=xxx"
    }
  }
}
```

### 3.1 字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.sku` | string | 实际命中的 SKU 名称 |
| `data.materialId` | string | 素材 ID |
| `data.productModel` | string | 所属 SPU / 型号 |
| `data.whiteBackgroundUploaded` | boolean | 是否已有白底图 |
| `data.whiteBackgroundComplete` | boolean | 固定 8 张是否已补齐 |
| `data.whiteBackgroundFixedCount` | number | 当前已上传的固定角度图数量 |
| `data.whiteBackgroundOtherCount` | number | 当前已上传的 other 图片数量 |
| `data.whiteBackgroundCount` | number | 当前白底图总数 |
| `data.missingViews` | array | 当前仍缺少的固定角度图 |
| `data.whiteBackground.fixed` | array | 当前已有的固定角度白底图，按固定顺序返回已存在项 |
| `data.whiteBackground.other` | array | 其他图片，可为空数组 |
| `data.downloadUrls.zip` | string | 当前 SKU 白底图整包 ZIP 下载链接 |

### 3.2 `fixed` 固定图顺序

固定图返回顺序固定为：

1. `leftFront45`：左前45°
2. `rightFront45`：右前45°
3. `leftBack45`：左后45°
4. `rightBack45`：右后45°
5. `front`：正视图
6. `back`：后视图
7. `left`：左视图
8. `right`：右视图

### 3.3 单张图片对象字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `key` | string | 固定图为固定角度 key；其他图固定为 `other` |
| `label` | string | 图片说明 |
| `fileName` | string | 文件名 |
| `fileSize` | number | 文件大小，单位字节 |
| `downloadUrl` | string | 单张图片下载链接 |

## 4. 下载方式

### 4.1 下载单张白底图

直接请求响应里的 `downloadUrl` 即可：

```http
GET https://3d.yydd.ai/api/external/download?token=xxx
```

返回内容为对应图片文件，例如：

- `image/png`
- `image/jpeg`

### 4.2 下载整包白底图 ZIP

直接请求：

```http
GET https://3d.yydd.ai/api/external/download?token=xxx
```

当 token 对应的是白底图 ZIP 时，返回：

- `Content-Type: application/zip`
- 文件名：`{SKU}_白底图.zip`

## 5. 错误响应

### 5.1 SKU 不存在

```json
{
  "success": false,
  "error": {
    "code": "SKU_NOT_FOUND",
    "message": "未找到对应的标准模型 SKU"
  }
}
```

### 5.2 SKU 数据重复

```json
{
  "success": false,
  "error": {
    "code": "SKU_NOT_UNIQUE",
    "message": "该 SKU 存在重复数据，暂无法对外提供白底图"
  }
}
```

### 5.3 白底图不存在

```json
{
  "success": false,
  "error": {
    "code": "WHITE_BACKGROUND_NOT_FOUND",
    "message": "该 SKU 暂无白底图"
  }
}
```

### 5.4 API Key 无效

```json
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key 无效或缺失"
  }
}
```

## 6. 接入建议

- **推荐主流程**：先查接口 → 拿到 `fixed` / `other` → 按需下载单张图
- 如果业务需要一次性拉全量，也可以直接使用 `downloadUrls.zip`
- `sku` 查询支持大小写不敏感，但建议调用方统一按大写传参，便于排查
- 接口不再要求固定 8 张必须补齐；只要该 SKU 已有任意白底图，就会返回当前已有图片
- 下载链接为带 token 的受控链接，建议由服务端调用，不建议直接暴露到前端页面

## 7. cURL 示例

### 7.1 查询白底图

```bash
curl -X GET \
  "https://3d.yydd.ai/api/external/standard-model-white-background?sku=TEXT001452" \
  -H "X-API-Key: 5073534d7a59babbc45397a8eac5943b"
```

### 7.2 下载单张图片

```bash
curl -L \
  "https://3d.yydd.ai/api/external/download?token=xxx" \
  -o left-front-45.png
```

### 7.3 下载整包 ZIP

```bash
curl -L \
  "https://3d.yydd.ai/api/external/download?token=xxx" \
  -o TEXT001452_白底图.zip
```

## 8. 当前联调结论

已验证：

- 旧任务平台接口 `GET /api/external/product-assets` 正常
- 旧下载接口 `GET /api/external/download?token=...` 正常
- 新白底图接口 `GET /api/external/standard-model-white-background` 正常
- 新白底图单图下载正常

如果后续还要继续开放更多素材接口，建议继续复用当前这套：

- `X-API-Key`
- `/api/external/*`
- token 下载链接