hunyuan-vision API

hunyuan-vision 的技術規格

什麼是 hunyuan-vision？

hunyuan-vision 是 Tencent Hunyuan 的多模態圖像理解模型，透過與 OpenAI 相容的 API 對外提供。在 Tencent 的官方示例中，它用於「圖像到文字」類型的任務：使用者將提示與圖像一起發送，模型會回答例如圖像中顯示了什麼等問題。

實際上，這使得 hunyuan-vision 適用於在聊天工作流程中需要視覺推理的應用，例如圖像標註、場景描述、UI 或螢幕截圖解讀、產品圖像分析，以及通用視覺問答。其整合模式對已使用 OpenAI 風格客戶端的團隊尤為便利，因為 Tencent 表示開發者只需替換端點與 API 金鑰設定即可切換。

hunyuan-vision 的主要功能

• 多模態圖像理解：hunyuan-vision 能在同一請求中同時接受文字與圖像內容，支援針對上傳的視覺素材進行具備圖像上下文的對話與問答。
• 與 OpenAI 相容的介面：Tencent 以與 Chat Completions 相同的一般請求結構提供 hunyuan-vision，可降低既有 AI 應用的遷移成本。
• 彈性的圖像輸入方式：官方示例顯示同時支援標準遠端圖像 URL 與 base64 編碼的 Data URL，便於處理公開資產或本地處理後的檔案。
• 對 SDK 友好的整合：Tencent 明確文件化了在 Python、Node.js、Go 與 cURL 風格 HTTP 請求中搭配 OpenAI SDK 的使用方式，方便嵌入既有後端服務。
• 基於聊天的工作流程：由於以聊天補全模型形式提供，hunyuan-vision 自然適用於圍繞 messages 結構組織請求的會話型應用、助理與工具鏈。
• 按使用量計算的圖像 token：Tencent 指出圖像成本取決於圖像尺寸，並以範圍而非固定值說明每張圖像的 token 消耗。

如何取得並整合 hunyuan-vision

步驟 1: 註冊取得 API 金鑰

若要使用 hunyuan-vision，首先需透過提供方的主控台建立並妥善保管您的 API 金鑰。Tencent 為其與 OpenAI 相容的 Hunyuan API 提供基於 API 金鑰的存取方式，並需在請求中以 Bearer token 形式傳遞。請將金鑰保存在如 HUNYUAN_API_KEY 的環境變數中，避免在前端程式或公開版本庫中暴露。

步驟 2: 向 hunyuan-vision API 發送請求

使用與 OpenAI 相容的端點，並將模型名稱指定為 hunyuan-vision。

curl --location 'https://api.hunyuan.cloud.tencent.com/v1/chat/completions' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HUNYUAN_API_KEY" \
  --data '{
    "model": "hunyuan-vision",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What is in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/image.jpg"
            }
          }
        ]
      }
    ]
  }'

您也可以透過將客戶端指向 Hunyuan 的 base URL 來使用與 OpenAI 相容的 SDK：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("HUNYUAN_API_KEY"),
    base_url="https://api.hunyuan.cloud.tencent.com/v1",
)

response = client.chat.completions.create(
    model="hunyuan-vision",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg"
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

此請求結構遵循 Tencent 公布的 hunyuan-vision 與 OpenAI 相容的官方示例。

步驟 3: 擷取並驗證結果

在使用與 OpenAI 相容的 SDK 時，通常從第一個補全選項讀取生成的回答，例如 response.choices[0].message.content。在生產環境中，請先確認圖像 URL 可達或 base64 載荷有效，隨後依據您的應用需求檢查返回描述的準確性、安全性與格式一致性。Tencent 的示例展示了標準的聊天補全回應處理流程，因此現有的驗證與日誌管線通常只需極少修改即可重用。