431 lines
8.4 KiB
Markdown
431 lines
8.4 KiB
Markdown
# 腾讯混元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`，可据此补充本文档
|