# 腾讯混元3D API 完整文档

> 基础地址: `https://3d.hunyuan.tencent.com`
> 签名算法: HMAC-SHA256（已破解，见 `hunyuan3d_sign.py`）

---

## 目录

1. [认证方式](#认证方式)
2. [通用响应格式](#通用响应格式)
3. [用户相关接口](#用户相关接口)
4. [作品管理接口](#作品管理接口)
5. [图生3D接口](#图生3d接口)
6. [文生3D接口](#文生3d接口)
7. [草图生3D接口](#草图生3d接口)
8. [3D动画生成接口](#3d动画生成接口)
9. [3D纹理生成接口](#3d纹理生成接口)
10. [3D智能拓扑接口](#3d智能拓扑接口)
11. [资源上传接口](#资源上传接口)
12. [分享接口](#分享接口)
13. [配置接口](#配置接口)
14. [生成模式参数总表](#生成模式参数总表)

---

## 认证方式

Cookie 会话认证。需要携带 `hunyuan_user` 和 `hunyuan_token` Cookie。

所有 API 请求需要在 URL 查询参数中附带签名:
- `timestamp`: 秒级时间戳
- `nonce`: 16位随机字符串
- `sign`: HMAC-SHA256签名

---

## 通用响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

- `code`: 业务状态码，`0` 表示成功
- `message`: 提示信息
- `data`: 实际返回数据

---

## 用户相关接口

### 1. 获取用户信息

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

**响应示例**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": "abb5e2f51b08416fb5459a5082504ea0",
    "userType": "external",
    "loginType": "email",
    "registered": true,
    "status": 2
  }
}
```

### 2. 获取用户配额

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

**请求体**:
```json
{"sceneType": "3dCreations"}
```

**响应示例**:
```json
{
  "date": "20260524",
  "totalQuota": 20,
  "remainQuota": 0,
  "consumeQuota": 20,
  "alarmQuota": 1,
  "userInviteQuota": 0,
  "perUserInviteQuotaCount": 30,
  "maxUserInviteQuota": 6
}
```

---

## 作品管理接口

### 3. 获取作品列表

- **URL**: `/api/3d/creations/list`
- **Method**: `POST`
- **描述**: 获取当前用户的3D作品列表

**请求体**:
```json
{
  "page": 1,
  "pageSize": 20
}
```

### 4. 获取作品数量

- **URL**: `/api/3d/creations/count`
- **Method**: `POST`
- **描述**: 获取作品数量

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

### 5. 查询作品详情/生成状态

- **URL**: `/api/3d/creations/detail`
- **Method**: `GET`
- **描述**: 查询3D生成任务的进度和结果

**查询参数**:
```
?creationsId={id}
```

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

### 6. 取消任务

- **URL**: `/api/3d/creations/cancel`
- **Method**: `POST`
- **描述**: 取消进行中的生成任务

---

## 图生3D接口

### 7. 触发图生3D

- **URL**: `/api/3d/creations/generations`
- **Method**: `POST`
- **描述**: 提交图片，触发3D模型生成

**请求体**:
```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
}
```

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sceneType` | string | 是 | 场景类型，固定 `playGround3D-2.0` |
| `count` | int | 是 | 生成数量，固定 `1` |
| `modelType` | string | 是 | 模型类型，`image2ModelV3.1` |
| `title` | string | 否 | 作品标题 |
| `style` | string | 否 | 风格，见下方风格表 |
| `imageList` | array | 是 | 图片URL列表（需先上传获取resourceId） |
| `enable_pbr` | bool | 否 | 是否启用PBR材质，默认 `true` |
| `enableLowPoly` | bool | 否 | 是否低多边形，默认 `false` |
| `faceCount` | int | 否 | 面数，`1500000` |

**风格(style)选项**:
- `""` - 默认
- `"sculpture"` - 石雕
- `"qinghuaci"` - 青花瓷
- `"china_style"` - 中国风
- `"cartoon"` - 卡通
- `"cyberpunk"` - 赛博朋克

**几何风格(geo_type)选项**:
- `"default"` - 默认
- `"voxel"` - 体素
- `"low_poly"` - 低多边形

---

## 文生3D接口

### 8. 触发文生3D

- **URL**: `/api/3d/creations/generations`
- **Method**: `POST`
- **描述**: 输入文本描述生成3D模型

**请求体**:
```json
{
  "sceneType": "playGround3D-2.0",
  "count": 1,
  "modelType": "text2ModelV3.1",
  "title": "银色的长剑",
  "style": "",
  "text": "银色的长剑",
  "enable_pbr": true,
  "enableLowPoly": false,
  "faceCount": 1500000
}
```

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `modelType` | string | 是 | `text2ModelV3.1` |
| `text` | string | 是 | 文本描述/提示词 |
| `title` | string | 否 | 作品标题 |
| `style` | string | 否 | 风格 |
| 其他 | - | - | 同图生3D |

**提示词示例**（来自配置）:
- "银色的长剑"
- "猫头鹰，大眼睛，深棕色"
- "粉色蝴蝶结"
- "橙色颈挂式耳机"
- "歼-20威龙"
- "装甲，机械风格，逼真，4K"
- "汉堡里面有酸黄瓜 生菜 牛肉饼和芝士"

---

## 草图生3D接口

### 9. 触发草图生3D

- **URL**: `/api/3d/creations/generations`
- **Method**: `POST`
- **描述**: 上传草图+提示词生成3D模型

**请求体**:
```json
{
  "sceneType": "playGround3D-2.0",
  "count": 1,
  "modelType": "sketch2ModelV3.1",
  "title": "",
  "style": "",
  "text": "一个穿着蓝色衣服的小男孩",
  "imageList": [
    "https://3d.hunyuan.tencent.com/api/3d/resource/download?resourceId=..."
  ],
  "enable_pbr": true,
  "enableLowPoly": false,
  "faceCount": 1500000
}
```

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `modelType` | string | 是 | `sketch2ModelV3.1` |
| `text` | string | 是 | 草图描述提示词 |
| `imageList` | array | 是 | 草图图片URL |

---

## 3D动画生成接口

### 10. 获取动画动作模板

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

**动作类型(motionType)**:

| ID | 名称 | 说明 |
|----|------|------|
| 9 | 跨步 | Capoeira |
| 10 | 摔倒 | FallingBackDeath |
| 11 | 跳跃 | Jumping |
| 12 | 踢腿 | Kicking |
| 13 | 挥击 | OneHandSwordCombo |
| 15 | 跑步 | TreadmillRunning |
| 16 | 跳舞 | TwistDance |

### 11. 触发3D动画生成

- **URL**: `/api/3d/creations/generations`
- **Method**: `POST`
- **描述**: 为3D模型绑定骨骼并生成动画

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

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `modelType` | string | 是 | `animation3dV2` |
| `motionType` | int | 是 | 动作类型ID |
| `imageList` | array | 是 | 要绑定的3D模型图片 |

---

## 3D纹理生成接口

### 12. 触发3D纹理生成

- **URL**: `/api/3d/creations/generations`
- **Method**: `POST`
- **描述**: 为白模生成纹理贴图

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

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `modelType` | string | 是 | `textureTo3DV2` |
| `text` | string | 是 | 纹理描述 |
| `imageList` | array | 是 | 白模图片URL |

---

## 3D智能拓扑接口

### 13. 触发3D智能拓扑（减面）

- **URL**: `/api/3d/creations/generations`
- **Method**: `POST`
- **描述**: 输入文本/图片/白模，生成布线规整的低面数模型

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

**参数说明**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `modelType` | string | 是 | `lowpolyV2` |
| `faceCount` | int | 否 | 目标面数：`5000`(低), `18000`(中), `30000`(高) |
| `topology_format` | string | 否 | 输出格式：`glb` 或 `obj` |
| `enableLowPoly` | bool | 否 | 必须设为 `true` |

---

## 资源上传接口

### 14. 获取上传凭证

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

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

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

### 15. 图片内容审核

- **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=..."
}
```

### 16. 下载资源

- **URL**: `/api/3d/resource/download`
- **Method**: `GET`
- **描述**: 下载图片或模型文件

**查询参数**:
```
?resourceId={id}
```

---

## 分享接口

### 17. 创建分享

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

**请求体**:
```json
{
  "contentType": "creation",
  "contentId": "creationsId",
  "sharedContent": "",
  "platform": "3dPlayground"
}
```

---

## 配置接口

### 18. 获取全局配置

- **URL**: `/api/3d/config`
- **Method**: `GET`
- **描述**: 获取前端配置，包含提示词示例、风格配置、模板等

**包含内容**:
- `promptExamples` - 文生3D提示词示例
- `styleConfig` - 风格配置（几何风格+纹理风格）
- `animation3dConfig` - 动画模板配置
- `sketchImageConfig` - 草图示例配置
- `gameTemplate` - 游戏角色模板
- `retopologize` - 拓扑减面配置

---

## 生成模式参数总表

| 生成模式 | modelType | sceneType | 特有参数 | 说明 |
|----------|-----------|-----------|----------|------|
| **图生3D** | `image2ModelV3.1` | `playGround3D-2.0` | `imageList` | 图片生成3D模型 |
| **文生3D** | `text2ModelV3.1` | `playGround3D-2.0` | `text` | 文本描述生成3D |
| **草图生3D** | `sketch2ModelV3.1` | `playGround3D-2.0` | `text`, `imageList` | 草图+提示词生成3D |
| **3D动画** | `animation3dV2` | `playGround3D-2.0` | `motionType` | 为模型绑定骨骼动画 |
| **3D纹理** | `textureTo3DV2` | `playGround3D-2.0` | `text`, `imageList` | 为白模生成纹理 |
| **智能拓扑** | `lowpolyV2` | `playGround3D-2.0` | `faceCount`(5000/18000/30000) | 减面优化 |

### 通用参数（所有模式）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `count` | int | 1 | 生成数量（固定1） |
| `title` | string | "" | 作品标题 |
| `style` | string | "" | 纹理风格 |
| `enable_pbr` | bool | true | PBR材质 |
| `enableLowPoly` | bool | false | 低多边形 |
| `faceCount` | int | 1500000 | 面数 |

### 风格参数

**纹理风格(style)**:
- `""` - 通用
- `"sculpture"` - 石雕
- `"qinghuaci"` - 青花瓷
- `"china_style"` - 中国风
- `"cartoon"` - 卡通
- `"cyberpunk"` - 赛博朋克

**几何风格(geo_type)**:
- `"default"` - 默认
- `"voxel"` - 体素
- `"low_poly"` - 低多边形

### 动作类型(motionType)

| ID | 动作 |
|----|------|
| 9 | 跨步(Capoeira) |
| 10 | 摔倒(FallingBackDeath) |
| 11 | 跳跃(Jumping) |
| 12 | 踢腿(Kicking) |
| 13 | 挥击(OneHandSwordCombo) |
| 15 | 跑步(TreadmillRunning) |
| 16 | 跳舞(TwistDance) |

---

## 完整调用流程

### 图生3D流程
```
1. POST /resource/genUploadInfo → 获取COS凭证
2. 上传图片到COS → 获取resourceUrl
3. POST /resource/review → 图片审核
4. POST /creations/generations → 触发生成
5. GET /creations/detail → 轮询状态
6. 下载模型文件(glb/obj)
```

### 文生3D流程
```
1. POST /creations/generations (带text参数) → 触发生成
2. GET /creations/detail → 轮询状态
3. 下载模型文件
```

### 动画生成流程
```
1. 先生成/上传3D模型
2. POST /creations/generations (modelType=animation3dV2, motionType=X)
3. GET /creations/detail → 轮询状态
4. 下载带动画的模型
```

---

## 限制与注意事项

1. **配额限制**: 每日20次生成配额
2. **频率限制**: 频繁调用会触发"今天操作频繁，请明天再试"
3. **count参数**: 必须固定为1，其他值会报错
4. **faceCount**: 图生3D固定1500000，拓扑减面用5000/18000/30000
5. **图片格式**: 必须通过腾讯COS上传获取resourceId