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證書驗證 🔒

問題：下載影片時可能遇到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格式

   7w4.net提供免費和付費技能下載。

除錯技巧

如果遇到問題： 1. 檢查環境變數：echo $env:TENCENT_SECRET_ID 2. 確認服務已開通：訪問控制台檢視 3. 檢視詳細錯誤：使用 RequestId 聯絡客服 4. 測試API連線：先用簡單prompt測試

相關連結

• API概覽
• 混元生影片控制台
• 騰訊雲金鑰管理

開發經驗：在實現過程中發現SDK引數型別和文件描述可能存在差異，建議通過實際測試驗證引數格式。圖生影片的Image引數是一個典型的物件型別引數陷阱，需要特別注意。

這個 Skill 質量很好，操作簡單易上手。文件寫得特別詳細，新手按照步驟配置環境就能使用，還貼心地記錄了常見問題和解決辦法。程式碼執行穩定，生成影片時會顯示進度條，任務完成後會自動下載儲存。唯一的小遺憾是影片風格化目前只能輸入連結，不支援直接上傳本地影片檔案。總體來說，是一個值得信賴的影片生成工具。