混元生3D模型能力

腾讯混元生3D API (OpenAI兼容接口) - 基于混元大模型的3D模型生成

Security Scan

The skill's code, instructions, and requested environment access are consistent with a Tencent Hunyuan 3D generation client and don't request unrelated permissions or install arbitrary software.

Purpose & Capability

Name/description, SKILL.md, and the included Python script all describe a 3D generation client using an OpenAI-compatible Tencent Hunyuan 3D API. Required binary (python) and required env var (HUNYUAN_3D_API_KEY) are appropriate and expected.

Instruction Scope

Runtime instructions tell the agent to set an API key env var and run the provided script which submits jobs, polls status, and downloads results. The instructions do not request reading unrelated files, other credentials, or exfiltrating data to any endpoint beyond the documented Tencent API and model-result URLs.

Install Mechanism

No install spec — instruction-only with a small bundled script. No external archives or unusual download/install steps are present.

Credentials

Only a single API key (HUNYUAN_3D_API_KEY) is required; that aligns with the documented OpenAI-compatible API Key authentication and is proportional to the skill's functionality.

Persistence & Privilege

Skill is not forced-always, uses normal autonomous invocation defaults, and does not request persistent system-wide configuration changes or permissions beyond writing its own output files.

Assessment

This skill appears to be a straightforward client for Tencent's Hunyuan 3D OpenAI-compatible API. Before installing/use: (1) Understand that running the script will send your prompts and any provided image URLs along with your HUNYUAN_3D_API_KEY to Tencent's api.ai3d.cloud.tencent.com service — only provide an API key you trust to be used for this purpose. (2) The script will download model artifacts to disk (./models by default); ensure you trust the sources of any image URLs you pass. (3) Storing the API key in shell startup files makes it persistent on that account — treat it like a secret and rotate/revoke it if compromised. (4) Review the bundled script if you want assurance (it's short and readable). If you need additional assurance, request provenance for the skill (author/source) or run it in an isolated environment.

Hunyuan 3D - 腾讯混元生3D (OpenAI兼容接口)

基于腾讯混元大模型的3D模型生成服务，使用OpenAI兼容接口，支持文生3D、图生3D。

⚠️ 重要说明

本技能使用OpenAI兼容接口，与传统的腾讯云API不同：

• 使用 API Key 认证（不是SecretId/SecretKey）
• 接口风格与OpenAI一致
• 仅支持专业版（不支持极速版）

🚀 快速开始

第一步：开通混元生3D服务

必须先在腾讯云控制台开通服务：

1. 访问 腾讯混元生3D控制台
2. 点击「立即开通」或「申请开通」
3. 阅读并同意服务协议
4. 等待服务开通（通常即时生效）

常见问题：

• 如果显示"资源不足"，说明服务正在初始化，请等待5-10分钟后再试
• 如果无法开通，可能需要实名认证或联系客服

第二步：获取API Key

1. 访问 混元生3D API Key管理页面
2. 点击「创建API Key」
3. 输入名称（如：hunyuan-3d-key）
4. 复制生成的API Key（格式：sk-xxxxx）

⚠️ 重要：API Key只显示一次，请妥善保存！

备用地址：如果上述链接无法访问，也可在 混元大模型API Key页面 创建

第三步：配置环境变量

⚠️ 重要区别：

• hunyuan-image 和 hunyuan-video 使用 腾讯云 SecretId/SecretKey
• hunyuan-3d 使用 混元3D专用 API Key（格式：sk-xxxxx）

需要的环境变量：

• HUNYUAN_3D_API_KEY - 混元3D API Key

Windows PowerShell:

# 临时设置（当前会话）
$env:HUNYUAN_3D_API_KEY = "sk-xxxxx"

# 永久设置（推荐）
[Environment]::SetEnvironmentVariable("HUNYUAN_3D_API_KEY", "sk-xxxxx", "User")

Linux/Mac:

# 临时设置
export HUNYUAN_3D_API_KEY="sk-xxxxx"

# 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
echo 'export HUNYUAN_3D_API_KEY="sk-xxxxx"' >> ~/.bashrc
source ~/.bashrc

第四步：验证配置

# 检查环境变量
Write-Host "API Key: $($env:HUNYUAN_3D_API_KEY.Substring(0,15))..."

# 测试生成
python scripts/generate.py --mode text --prompt "一只小狗"

如果报错"资源不足"：服务正在初始化，等待5-10分钟后重试

python scripts/generate.py --mode text --prompt "一只小狗"

如果看到「任务提交成功」，说明配置正确！

功能

• 文生3D：通过文本描述生成3D模型
• 图生3D：通过图片生成3D模型
• 多版本支持：支持模型版本3.0和3.1

使用方法

基础用法

# 文生3D
python scripts/generate.py --mode text --prompt "一只可爱的小猪"

# 图生3D
python scripts/generate.py --mode image --image-url "https://example.com/pig.jpg"

# 使用3.1版本模型
python scripts/generate.py --mode text --prompt "小狗" --model 3.1

参数说明

参数	说明	示例
--mode	生成模式	text(文生3D), image(图生3D)
--prompt	文本描述（文生3D）	"一只可爱的小猪"
--image-url	图片URL（图生3D）	"https://example.com/pig.jpg"
--model	模型版本	3.0(默认), 3.1
--output	输出目录	./models

模型版本说明

版本	特点
3.0	默认版本，功能完整
3.1	新版本，但LowPoly和Sketch参数不可用

输入要求

文生3D：

• 文本描述：最多1024个utf-8字符
• 支持中文提示词

图生3D：

• 图片格式：jpg, png, jpeg, webp
• 图片大小：≤8MB
• 分辨率：128px ~ 5000px（单边）

输出

生成的3D模型保存在 {output}/{date}/{job_id}/ 目录下：

• model.{format} - 3D模型文件（obj/glb格式）
• info.json - 任务信息

输出格式：

• 同时返回 .glb 和 .obj 格式
• 包含纹理贴图
• 附带预览图

接口信息

• Base URL: https://api.ai3d.cloud.tencent.com
• 提交任务: POST /v1/ai3d/submit
• 查询任务: POST /v1/ai3d/query
• 认证方式: API Key (Header: Authorization: sk-xxxxx)

踩坑记录与解决方案

1. 服务未开通 - ResourceUnavailable

错误现象：

ResourceUnavailable.NotExist - 计费状态未知

解决方案：

1. 访问 https://console.cloud.tencent.com/ai3d
2. 点击「立即开通」
3. 等待5-10分钟让服务初始化
4. 重试

2. 资源不足 - ResourceInsufficient

错误现象：

ResourceInsufficient - 资源不足

解决方案：

• 服务刚开通时可能出现，等待5-10分钟后重试
• 如果持续出现，联系腾讯云客服

3. API Key错误 - Unauthorized

错误现象：

HTTP 401: Unauthorized
Incorrect API key provided

解决方案：

1. 确认使用的是 API Key（不是SecretId/SecretKey）
2. API Key格式应为 sk-xxxxx
3. 在 https://console.cloud.tencent.com/hunyuan/start 创建
4. 检查环境变量是否正确设置

4. 响应格式问题

发现：OpenAI兼容接口返回格式为：

{
  "Response": {
    "JobId": "xxx",
    "Status": "DONE",
    "ResultFile3Ds": [...]
  }
}

注意：状态字段是 Status 不是 StatusCode，成功状态是 DONE 不是 SUCCESS

5. 模型版本3.1的限制

注意：选择3.1版本时，LowPoly和Sketch参数不可用

6. 图片格式不支持

错误：图片上传失败

解决：只支持jpg, png, jpeg, webp格式

完整示例

# 示例1：生成小猪3D模型
python scripts/generate.py --mode text --prompt "一只可爱的小猪，粉色，卡通风格"

# 示例2：通过图片生成3D
python scripts/generate.py --mode image --image-url "https://example.com/pig-photo.jpg"

# 示例3：使用3.1版本
python scripts/generate.py --mode text --prompt "小狗" --model 3.1

# 示例4：指定输出目录
python scripts/generate.py --mode text --prompt "小猫" --output ./my_models

注意事项

1. 异步接口：分为提交任务和查询任务两个步骤
2. 任务有效期：24小时
3. 并发限制：默认3个并发
4. 仅专业版：OpenAI兼容接口不支持极速版
5. API Key：使用单独的API Key，不是腾讯云SecretId/SecretKey
6. 生成时间：3D生成需要较长时间（1-5分钟），请耐心等待

相关链接

• OpenAI兼容接口文档
• API Key管理
• 混元生3D控制台
• 提交任务API文档

调试技巧

如果遇到问题，可以：

1. 检查环境变量：echo $env:HUNYUAN_3D_API_KEY
2. 测试API Key是否有效（见上文curl示例）
3. 查看腾讯云控制台的服务状态
4. 使用RequestId联系客服查询