600 lines
13 KiB
Markdown
600 lines
13 KiB
Markdown
# 腾讯混元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
|