hunyuan-vision API

hunyuan-vision の技術仕様

hunyuan-vision とは？

hunyuan-vision は、OpenAI 互換 API 経由で提供される Tencent Hunyuan のマルチモーダル画像理解モデルです。Tencent の公式例では、ユーザーが画像とともにプロンプトを送信し、画像に何が写っているかといった問いにモデルが答える「image-to-text」スタイルのタスクに用いられています。

実用面では、キャプション生成、シーン記述、UI やスクリーンショットの解釈、製品画像の分析、一般的な視覚質問応答など、チャットのワークフローで視覚的推論が必要なアプリケーションに適しています。特に OpenAI スタイルのクライアントをすでに利用しているチームにとって、エンドポイントと API キー設定を置き換えるだけで切り替えられると Tencent が述べているため、統合が容易です。

hunyuan-vision の主な機能

• マルチモーダル画像理解: hunyuan-vision は同一リクエスト内でテキストと画像の両方を受け付け、アップロードされたビジュアルに関する会話や質問応答を可能にします。
• OpenAI 互換インターフェース: Tencent は Chat Completions と同様のリクエスト構造で hunyuan-vision を提供しており、既存の AI アプリケーションからの移行コストを抑えます。
• 柔軟な画像入力方法: 公式例では、標準的なリモート画像 URL に加え、base64 エンコードされたデータ URL もサポートしており、公開アセットでもローカル処理済みファイルでも扱いやすくなっています。
• SDK に優しい統合: Python、Node.js、Go、cURL スタイルの HTTP リクエストでの OpenAI SDK 利用が明示されており、既存のバックエンドサービスに容易に組み込めます。
• チャットベースのワークフロー: チャット補完モデルとして公開されているため、messages を中心にリクエストを構成する会話型アプリ、アシスタント、ツールチェーンに自然に適合します。
• 使用量に基づく画像トークン計測: 画像コストは画像サイズに依存し、1 枚あたりのトークン消費は範囲で示されます。

hunyuan-vision へのアクセスと統合方法

ステップ 1: API キーの取得

hunyuan-vision にアクセスするには、まずプロバイダーのコンソールで API キーを作成し、安全に保管します。Tencent は OpenAI 互換の Hunyuan API で API キーによるアクセス方法を記載しており、キーはリクエストで Bearer トークンとして渡します。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 のベース 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)

このリクエスト構造は、hunyuan-vision に関する Tencent の OpenAI 互換公式サンプルに準拠しています。

ステップ 3: 結果の取得と検証

OpenAI 互換 SDK を使用する場合、生成された回答は通常 response.choices[0].message.content から読み取ります。プロダクション運用では、画像 URL にアクセスできるか、あるいは base64 ペイロードが有効かを確認し、返された説明がアプリケーション要件（正確性、安全性、書式の一貫性）を満たしているかをチェックしてください。Tencent の例では標準的なチャット補完のレスポンス処理が示されており、既存の検証やログ記録のパイプラインは最小限の変更で再利用できる場合が多いです。