# 腾讯混元3D API 文档

> 基础地址: `https://3d.hunyuan.tencent.com`

---

## 认证方式

Cookie 会话认证。登录后由浏览器自动携带 `sessionid` 等 Cookie。

持久化数据保存在 `./hunyuan3d_profile`，CloakBrowser 复用该目录即可保持登录态。

---

## 通用响应格式

**注意**：接口响应格式不统一，分为两类：

**A. 扁平格式**（大多数 GET 及数据查询接口）：
```json
{
  "key": "value"
}
```

**B. 包装格式**（部分 POST 操作接口）：
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

- `code`: 业务状态码，`0` 表示成功
- `message` / `msg`: 提示信息（字段名不统一）
- `data`: 实际返回数据

---

## 接口列表

### 1. 获取用户信息

- **URL**: `/api/3d/getuserinfo`
- **Method**: `GET`
- **描述**: 获取当前登录用户的基本信息

**响应示例**（扁平格式）:
```json
{
  "userId": "...",
  "nickname": "...",
  "imageUrl": "...",
  "loginType": "email",
  "registered": true
}
```

---

### 2. 获取用户配额

- **URL**: `/api/3d/quotainfo`
- **Method**: `GET`
- **描述**: 获取当前用户的生成配额/剩余次数

**响应示例**（扁平格式）:
```json
{
  "date": "20260524",
  "totalQuota": 20,
  "remainQuota": 17,
  "consumeQuota": 3
}
```

---

### 3. 获取工作流模板

- **URL**: `/api/3d/workflow/action/templates`
- **Method**: `GET`
- **描述**: 获取可用的3D生成工作流模板列表

**响应示例**（扁平格式）:
```json
{
  "templates": [
    {
      "name": "跨步",
      "value": "9",
      "fbx": "https://...",
      "glb": "https://...",
      "image": "https://...",
      "preview": "https://...",
      "visible": true
    }
  ]
}
```

---

### 4. 获取通知列表

- **URL**: `/api/3d/notice/list`
- **Method**: `GET`
- **描述**: 获取系统通知/公告列表

**响应示例**:
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "...",
      "title": "...",
      "content": "...",
      "create_time": "..."
    }
  ]
}
```

---

### 5. 获取作品数量

- **URL**: `/api/3d/creations/count`
- **Method**: `POST`
- **描述**: 获取当前用户已生成的作品总数

**请求体**:
```json
{
  "statusList": ["wait", "processing", "success", "fail"]
}
```

**响应示例**（扁平格式）:
```json
{
  "count": 42
}
```

---

### 6. 分享相关

- **URL**: `/api/3d/share`
- **Method**: `POST`
- **描述**: 创建分享链接或获取分享信息

**请求体**:
```json
{
  "creation_id": "..."
}
```

**响应示例**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "share_url": "https://3d.hunyuan.tencent.com/share/..."
  }
}
```

---

## 图生3D 完整流程

### 7. 获取图片上传凭证

- **URL**: `/api/3d/resource/genUploadInfo`
- **Method**: `POST`
- **描述**: 获取腾讯云 COS 临时上传凭证

**请求体**:
```json
{
  "fileName": "your_image.png"
}
```

**响应示例**:
```json
{
  "error": {
    "code": "0",
    "message": ""
  },
  "bucketName": "hunyuan-base-prod-1258344703",
  "region": "ap-guangzhou",
  "location": "hunyuan3d/default/xxx/xxx.png",
  "encryptTmpSecretId": "...",
  "encryptTmpSecretKey": "...",
  "encryptToken": "...",
  "startTime": 1779562912,
  "expiredTime": 1811098912,
  "resourceUrl": "https://3d.hunyuan.tencent.com/api/3d/resource/download?resourceId=..."
}
```

---

### 8. 图片内容审核

- **URL**: `/api/3d/resource/review`
- **Method**: `POST`
- **描述**: 上传前对图片进行安全审核

**请求体**:
```json
{
  "sceneType": "playGround3D-2.0",
  "text": "",
  "resourceType": "image",
  "resourceUrl": "https://3d.hunyuan.tencent.com/api/3d/resource/download?resourceId=..."
}
```

**响应示例**:
```json
{
  "code": 0,
  "msg": "",
  "result": {
    "text": { "code": 0 },
    "name": { "code": 0 },
    "resource": { "code": 0 }
  },
  "id": "..."
}
```

---

### 9. 触发3D生成

- **URL**: `/api/3d/creations/generations?timestamp={ts}&nonce={nonce}&sign={sign}`
- **Method**: `POST`
- **描述**: 提交图片，触发3D模型生成任务。URL 带有签名参数防重放。

**请求体**:
```json
{
  "sceneType": "playGround3D-2.0",
  "count": 1,
  "modelType": "image2ModelV3.1",
  "title": "",
  "style": "",
  "imageList": [
    "https://3d.hunyuan.tencent.com/api/3d/resource/download?resourceId=..."
  ],
  "enable_pbr": true,
  "enableLowPoly": false,
  "faceCount": 1500000
}
```

**参数说明**:
- `modelType`: `image2ModelV3.1` (图生3D V3.1)
- `faceCount`: 模型面数，`1500000` 对应 1.5m，`1000000` 对应 1m，`500000` 对应 500k，`50000` 对应 50k
- `enable_pbr`: 是否启用 PBR 材质
- `imageList`: 已上传图片的 `resourceUrl` 列表

**响应**: 返回 `creationsId`，用于后续轮询生成状态。

---

### 10. 文生3D

- **URL**: `/api/3d/creations/generations?timestamp={ts}&nonce={nonce}&sign={sign}`
- **Method**: `POST`
- **描述**: 输入文本描述，触发3D模型生成。接口地址和图生3D相同，仅请求体参数不同。

**请求体**:
```json
{
  "sceneType": "playGround3D-2.0",
  "count": 4,
  "modelType": "text2ModelV3.1",
  "title": "一只银白色的鲑鱼",
  "style": "",
  "prompt": "一只银白色的鲑鱼",
  "enable_pbr": true,
  "enableLowPoly": false,
  "faceCount": 1500000
}
```

**参数说明**:
- `modelType`: `text2ModelV3.1` (文生3D V3.1)
- `count`: 一次生成的候选数量，默认 `4`
- `title` / `prompt`: 文本描述，建议以单主体为主
- `faceCount`: 模型面数，`1500000`(1.5m) / `1000000`(1m) / `500000`(500k) / `50000`(50k)
- `enable_pbr`: 是否启用 PBR 材质
- `style`: 纹理风格，可选 `通用`、`石雕`、`青花瓷`、`中国风`、`卡通`、`赛博朋克`

**响应**: 返回 `creationsId`，用于后续轮询生成状态。

---

### 11. 查询生成状态（轮询）

- **URL**: `/api/3d/creations/detail?creationsId={id}`
- **Method**: `GET`
- **描述**: 轮询查询3D生成任务的进度和结果。前端约每 2~3 秒轮询一次。

**响应示例**（扁平格式）:
```json
{
  "id": "355e2c8b-eaab-4e22-a521-375c7c2fcc2e",
  "status": "processing",
  "prompt": "...",
  "result": [
    {
      "taskId": "...",
      "status": "processing",
      "progress": 21,
      "urlResult": {
        "glb": "https://...",
        "obj": "https://...",
        "image_url": "https://..."
      }
    }
  ]
}
```

**状态说明**:
- `wait`: 排队中
- `processing`: 生成中
- `success`: 生成完成
- `fail`: 生成失败

---

### 12. 获取作品列表（资产）

- **URL**: `/api/3d/creations/list`
- **Method**: `POST`
- **描述**: 获取当前用户的3D作品列表，对应「资产」页面。

**响应示例**（扁平格式）:
```json
{
  "totalCount": 10,
  "creations": [
    {
      "id": "...",
      "title": "一只银白色的鲑鱼",
      "status": "success",
      "modelType": "text2ModelV3.1",
      "result": [...]
    }
  ]
}
```

---

### 13. 获取作品数量

- **URL**: `/api/3d/creations/count`
- **Method**: `POST`
- **描述**: 获取当前用户的作品总数及各状态数量

---

### 14. 下载资源文件

- **URL**: `/api/3d/resource/download?resourceId={id}`
- **Method**: `GET`
- **描述**: 下载图片或模型文件（二进制流）

---

## 完整调用流程（文生3D）

```
1. POST /api/3d/creations/generations
   → 提交文本描述，得到 creationsId

2. GET /api/3d/creations/detail?creationsId=xxx
   → 轮询直到 status == "success"

3. 从 detail 响应中提取 modelUrl / previewUrl 下载模型
```

**与图生3D的区别**：文生3D无需图片上传和审核，直接调用 generations 接口即可。

---

## 完整调用流程（图生3D）

```
1. POST /api/3d/resource/genUploadInfo
   → 获取 COS 临时凭证

2. 用临时凭证把图片上传到腾讯云 COS
   → 得到 resourceUrl

3. POST /api/3d/resource/review
   → 图片安全审核通过

4. POST /api/3d/creations/generations
   → 触发3D生成，得到 creationsId

5. GET /api/3d/creations/detail?creationsId=xxx
   → 轮询直到 status == "success"

6. 从 detail 响应中提取 modelUrl / previewUrl 下载模型
```

---

## 使用建议

1. 运行 `hunyuan3d_login.py` 完成登录，持久化 Cookie
2. 运行 `hunyuan3d_api_sniffer.py` 拦截实际操作中的完整请求和响应
3. 在浏览器中手动触发各种操作（生成、分享、删除等），终端会实时打印 API 调用
4. 结果保存到 `api_requests.log.json`，可据此补充本文档