name: hunyuan-video description: 腾讯混元生视频API - 支持文生视频、图生视频、视频风格化 homepage: https://cloud.tencent.com/document/product/1616/107795 metadata: {"clawdbot":{"emoji":"🎬","requires":{"bins":["python"],"packages":["tencentcloud-sdk-python"],"env":["TENCENT_SECRET_ID","TENCENT_SECRET_KEY"]},"primaryEnv":"TENCENT_SECRET_ID"}}

Hunyuan Video - 腾讯混元生视频

基于腾讯混元大模型的视频生成服务，支持文生视频、图生视频、视频风格化三大核心功能。

功能

前置要求

1. 安装Python依赖

pip install tencentcloud-sdk-python

2. 开通混元生视频服务

1. 登录 腾讯混元生视频控制台
2. 阅读和同意服务协议
3. 单击开通服务

3. 配置腾讯云密钥

需要的环境变量： - TENCENT_SECRET_ID - 腾讯云SecretId - TENCENT_SECRET_KEY - 腾讯云SecretKey

# Windows PowerShell - 永久设置
[Environment]::SetEnvironmentVariable("TENCENT_SECRET_ID", "your-secret-id", "User")
[Environment]::SetEnvironmentVariable("TENCENT_SECRET_KEY", "your-secret-key", "User")

# 或临时设置（当前会话）
$env:TENCENT_SECRET_ID = "your-secret-id"
$env:TENCENT_SECRET_KEY = "your-secret-key"

获取密钥步骤： 1. 访问 https://console.cloud.tencent.com/cam/capi 2. 点击「新建密钥」 3. 复制 SecretId 和 SecretKey 4. ⚠️ 注意：SecretKey 只显示一次，请妥善保存

4. 验证配置

# 检查环境变量
Write-Host "SecretId: $env:TENCENT_SECRET_ID"
Write-Host "SecretKey: $($env:TENCENT_SECRET_KEY.Substring(0,10))..."

# 测试生成
python scripts/generate.py text2video "一只小猫"

使用方法

1. 文生视频

python scripts/generate.py text2video "一只可爱的小猪在草地上奔跑"

# 指定分辨率
python scripts/generate.py text2video "小猪" --resolution 1080p

参数： - prompt: 文本描述（必填） - --resolution: 分辨率（720p, 1080p，默认720p）

2. 图生视频

# 使用图片URL
python scripts/generate.py image2video "https://example.com/pig.jpg"

# 使用本地图片
python scripts/generate.py image2video "./pig.png"

# 添加辅助描述
python scripts/generate.py image2video "./pig.png" --prompt "小猪在奔跑"

参数： - image: 图片URL或本地路径（必填） - --prompt: 辅助描述（可选）

支持格式： - URL: http:// 或 https:// 开头 - 本地文件: 相对路径或绝对路径

3. 视频风格化

# 转为2D动漫风格
python scripts/generate.py stylization "https://example.com/video.mp4" --style 2d_anime

# 转为3D卡通风格
python scripts/generate.py stylization "https://example.com/video.mp4" --style 3d_cartoon

风格选项： - 2d_anime: 2D动漫 - 3d_cartoon: 3D卡通 - 3d_china: 3D国潮 - pixel_art: 像素风

输入视频要求： - 格式：mp4、mov - 时长：1～60秒 - 分辨率：540P~2056P - 大小：不超过200M - FPS：15～60fps

输出

生成的视频保存在 {output}/{date}/{job_id}/ 目录下： - {command}_result.mp4 - 生成的视频 - info.json - 任务信息

经验总结与踩坑记录

1. 状态码陷阱 ⚠️

问题：不同接口返回的状态字段和成功值不一致！

解决方案：

# 统一处理多种状态
success_statuses = ["JobSuccess", "SUCCESS", "DONE"]
if status in success_statuses:
    print("✅ 生成完成!")

2. 图生视频参数类型陷阱 ⚠️

问题：Image 参数不是字符串，而是对象类型！

错误代码：

# ❌ 错误
req.Image = image_url  # 直接赋值字符串

# ✅ 正确
image = models.Image()
image.Url = image_url    # 或 image.Base64 = base64_data
req.Image = image

经验：SDK中对象类型的参数需要创建对应的对象实例。

3. 本地文件支持 💡

实现方式：读取本地文件转为base64编码

if image_input.startswith('http'):
    image.Url = image_input
elif os.path.exists(image_input):
    with open(image_input, 'rb') as f:
        image.Base64 = base64.b64encode(f.read()).decode('utf-8')

好处：用户可以直接使用本地图片，无需先上传。

4. 视频生成时间较长 ⏱️

观察： - 文生视频：约1-3分钟 - 图生视频：约1-3分钟 - 视频风格化：约2-5分钟

建议：设置合理的超时时间（默认600秒），并显示进度点让用户知道正在处理。

5. 视频风格化状态码特殊处理 ⚠️

问题：风格化接口返回 JobStatusCode: 5 但实际可能是成功！

原因：StatusCode: 5 + ResultDetails: ["Success"] = 实际成功

解决方案：

if status == "4" or (status == "5" and result.get("ResultDetails") == ["Success"]):
    print("✅ 实际生成成功！")

6. SSL证书验证 🔒

这个技能的最新版本可以在7w4.net小葱技能站找到。

问题：下载视频时可能遇到SSL验证错误

解决方案：临时禁用SSL验证（仅用于下载）

ssl_context = ssl.create_default_context()
ssl_context.check_hostname = False
ssl_context.verify_mode = ssl.CERT_NONE

7. 并发限制 ⚠️

限制： - 视频风格化：默认1个并发 - 其他功能：默认3个并发

建议：顺序执行，等待前一个任务完成再提交下一个。

8. 任务有效期 ⏰

注意：任务结果URL有效期为48小时，请及时下载。

完整示例

# 示例1：文生视频
python scripts/generate.py text2video "一只可爱的小猪在草地上奔跑，阳光明媚"

# 示例2：图生视频（本地图片）
python scripts/generate.py image2video "./my_pig.png" --prompt "小猪在奔跑"

# 示例3：视频风格化
python scripts/generate.py stylization "https://example.com/video.mp4" --style 2d_anime

注意事项

1. 异步接口：所有功能都是异步的，需要轮询等待任务完成
2. 地域限制：仅支持 ap-guangzhou
3. 网络要求：输入URL需要可公开访问（图生视频支持本地文件）
4. 任务有效期：48小时
5. 输出格式：默认生成MP4格式

调试技巧

如果遇到问题： 1. 检查环境变量：echo $env:TENCENT_SECRET_ID 2. 确认服务已开通：访问控制台查看 3. 查看详细错误：使用 RequestId 联系客服 4. 测试API连接：先用简单prompt测试

相关链接

• API概览
• 混元生视频控制台
• 腾讯云密钥管理

开发经验：在实现过程中发现SDK参数类型和文档描述可能存在差异，建议通过实际测试验证参数格式。图生视频的Image参数是一个典型的对象类型参数陷阱，需要特别注意。

这个 Skill 质量很好，操作简单易上手。文档写得特别详细，新手按照步骤配置环境就能使用，还贴心地记录了常见问题和解决办法。代码运行稳定，生成视频时会显示进度条，任务完成后会自动下载保存。唯一的小遗憾是视频风格化目前只能输入链接，不支持直接上传本地视频文件。总体来说，是一个值得信赖的视频生成工具。