KawasakiAkasei/hunyuan3dweb

Fork 0

Files

KawasakiAkasei 2ce35563c4 Initial commit

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

8.4 KiB

Raw Blame History

腾讯混元3D API 文档

基础地址: https://3d.hunyuan.tencent.com

认证方式

Cookie 会话认证。登录后由浏览器自动携带 sessionid 等 Cookie。

持久化数据保存在 ./hunyuan3d_profile，CloakBrowser 复用该目录即可保持登录态。

通用响应格式

注意：接口响应格式不统一，分为两类：

A. 扁平格式（大多数 GET 及数据查询接口）：

{
  "key": "value"
}

B. 包装格式（部分 POST 操作接口）：

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

code: 业务状态码，0 表示成功
message / msg: 提示信息（字段名不统一）
data: 实际返回数据

接口列表

1. 获取用户信息

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

响应示例（扁平格式）:

{
  "userId": "...",
  "nickname": "...",
  "imageUrl": "...",
  "loginType": "email",
  "registered": true
}

2. 获取用户配额

URL: /api/3d/quotainfo
Method: GET
描述: 获取当前用户的生成配额/剩余次数

响应示例（扁平格式）:

{
  "date": "20260524",
  "totalQuota": 20,
  "remainQuota": 17,
  "consumeQuota": 3
}

3. 获取工作流模板

URL: /api/3d/workflow/action/templates
Method: GET
描述: 获取可用的3D生成工作流模板列表

响应示例（扁平格式）:

{
  "templates": [
    {
      "name": "跨步",
      "value": "9",
      "fbx": "https://...",
      "glb": "https://...",
      "image": "https://...",
      "preview": "https://...",
      "visible": true
    }
  ]
}

4. 获取通知列表

URL: /api/3d/notice/list
Method: GET
描述: 获取系统通知/公告列表

响应示例:

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "...",
      "title": "...",
      "content": "...",
      "create_time": "..."
    }
  ]
}

5. 获取作品数量

URL: /api/3d/creations/count
Method: POST
描述: 获取当前用户已生成的作品总数

请求体:

{
  "statusList": ["wait", "processing", "success", "fail"]
}

响应示例（扁平格式）:

{
  "count": 42
}

6. 分享相关

URL: /api/3d/share
Method: POST
描述: 创建分享链接或获取分享信息

请求体:

{
  "creation_id": "..."
}

响应示例:

{
  "code": 0,
  "message": "success",
  "data": {
    "share_url": "https://3d.hunyuan.tencent.com/share/..."
  }
}

图生3D 完整流程

7. 获取图片上传凭证

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

请求体:

{
  "fileName": "your_image.png"
}

响应示例:

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

请求体:

{
  "sceneType": "playGround3D-2.0",
  "text": "",
  "resourceType": "image",
  "resourceUrl": "https://3d.hunyuan.tencent.com/api/3d/resource/download?resourceId=..."
}

响应示例:

{
  "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 带有签名参数防重放。

请求体:

{
  "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相同，仅请求体参数不同。

请求体:

{
  "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 秒轮询一次。

响应示例（扁平格式）:

{
  "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作品列表，对应「资产」页面。

响应示例（扁平格式）:

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

使用建议

运行 hunyuan3d_login.py 完成登录，持久化 Cookie
运行 hunyuan3d_api_sniffer.py 拦截实际操作中的完整请求和响应
在浏览器中手动触发各种操作（生成、分享、删除等），终端会实时打印 API 调用
结果保存到 api_requests.log.json，可据此补充本文档

8.4 KiB Raw Blame History Unescape Escape

腾讯混元3D API 文档

认证方式

通用响应格式

接口列表

1. 获取用户信息

2. 获取用户配额

3. 获取工作流模板

4. 获取通知列表

5. 获取作品数量

6. 分享相关

图生3D 完整流程

7. 获取图片上传凭证

8. 图片内容审核

9. 触发3D生成

10. 文生3D

11. 查询生成状态（轮询）

12. 获取作品列表（资产）

13. 获取作品数量

14. 下载资源文件

完整调用流程（文生3D）

完整调用流程（图生3D）

使用建议

8.4 KiB

Raw Blame History