Initial commit

2026-05-24 21:47:44 +08:00
commit 2ce35563c4
20 changed files with 3698 additions and 0 deletions
--- a/doc/api_complete.md
+++ b/doc/api_complete.md
@@ -0,0 +1,599 @@
+# 腾讯混元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