KawasakiAkasei/hunyuan3dweb

Fork 0

Files

KawasakiAkasei 2ce35563c4 Initial commit

2026-05-24 21:47:44 +08:00

13 KiB

Raw Blame History

腾讯混元3D API 完整文档

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

认证方式

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

所有 API 请求需要在 URL 查询参数中附带签名:

timestamp: 秒级时间戳
nonce: 16位随机字符串
sign: HMAC-SHA256签名

通用响应格式

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

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

用户相关接口

1. 获取用户信息

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

响应示例:

{
  "code": 0,
  "message": "success",
  "data": {
    "userId": "abb5e2f51b08416fb5459a5082504ea0",
    "userType": "external",
    "loginType": "email",
    "registered": true,
    "status": 2
  }
}

2. 获取用户配额

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

请求体:

{"sceneType": "3dCreations"}

响应示例:

{
  "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作品列表

请求体:

{
  "page": 1,
  "pageSize": 20
}

4. 获取作品数量

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

请求体:

{"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模型生成

请求体:

{
  "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模型

请求体:

{
  "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模型

请求体:

{
  "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模型绑定骨骼并生成动画

请求体:

{
  "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
描述: 为白模生成纹理贴图

请求体:

{
  "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
描述: 输入文本/图片/白模，生成布线规整的低面数模型

请求体:

{
  "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临时上传凭证

请求体:

{"fileName": "your_image.png"}

响应示例:

{
  "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
描述: 上传前对图片进行安全审核

请求体:

{
  "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
描述: 创建分享链接

请求体:

{
  "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. 下载带动画的模型

限制与注意事项

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

13 KiB Raw Blame History Unescape Escape

腾讯混元3D API 完整文档

目录

认证方式

通用响应格式

用户相关接口

1. 获取用户信息

2. 获取用户配额

作品管理接口

3. 获取作品列表

4. 获取作品数量

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

6. 取消任务

图生3D接口

7. 触发图生3D

文生3D接口

8. 触发文生3D

草图生3D接口

9. 触发草图生3D

3D动画生成接口

10. 获取动画动作模板

11. 触发3D动画生成

3D纹理生成接口

12. 触发3D纹理生成

3D智能拓扑接口

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

资源上传接口

14. 获取上传凭证

15. 图片内容审核

16. 下载资源

分享接口

17. 创建分享

配置接口

18. 获取全局配置

生成模式参数总表

通用参数（所有模式）

风格参数

动作类型(motionType)

完整调用流程

图生3D流程

文生3D流程

动画生成流程

限制与注意事项

13 KiB

Raw Blame History