概要:本記事では、OpenAI Python SDK を使ってテンセント混元 Hy4 API を非ストリーミング方式で呼び出し、最初のテキストのみのリクエストを実行します。さらに、結果の検証方法、コストの見積もり方法、請求書の確認方法、よくあるエラーの対処方法についても説明します。
直接の答え:テンセント混元 Hy4 API は、APIYI の OpenAI 互換インターフェース経由で接続できます。3 つの設定を用意するだけで、最初のリクエストを送信できます:
- キー:
api.apiyi.com/tokenで作成し、環境変数APIYI_API_KEYに設定します。 - SDK のベース URL:
https://api.apiyi.com/v1。 - モデル ID:
hy4。
対応する HTTP エンドポイントは POST https://api.apiyi.com/v1/chat/completions です。2026-11-21 時点の料金表では、Hy4 の 100 万トークンあたりの価格は次のとおりです:キャッシュ未ヒットの入力が $0.85、出力が $2.55、キャッシュ読み取りが $0.045。実際の課金は APIYI の料金表に準拠します。URL は docs.apiyi.com/models(テンセントカテゴリ)です。
タイムラインは次のとおりです:テンセントは 11 月 4 日に Hy4 正式版をリリースし、11 月 20 日に重みを公開しました。APIYI は重み公開より前にこのモデルをラインナップに追加しており、追加のお知らせは docs.apiyi.com/news/hy4-launch に掲載されています。お知らせにはストリーミングの例がすでに含まれているため、本記事では残りの 4 点、すなわち非ストリーミング呼び出し、結果の検証、請求書の確認、失敗時のトラブルシューティングのみを扱います。お知らせでは Hy4 が画像入力に対応していることに触れていますが、本記事ではテキストのみを実演します。動画、Responses インターフェース、Computer Use はいずれも本記事の対象外であり、記事中に実測データは一切ありません。

テンセント混元 Hy4 API 導入のナレッジマップと読む順序
全体の流れは4つのステップに分かれ、前のステップの成果が次のステップの入力になります。番号順に読むことをおすすめします。第4節はエラー発生時に個別に参照できます。
| ステップ | 対応する本文 | なぜここに置くのか | 合格基準 |
|---|---|---|---|
| リクエストの準備 | 1.1、1.2 | エンドポイントやモデル名、Keyを間違えると、以降のステップがすべて失敗する | SDKがインポートできる、環境変数からKeyを読み取れる、コード内にKeyが平文で書かれていない |
| 初回呼び出し | 2.1、2.2 | まず顧客データを含まない短いテキストで経路が通ることを確認する | 返却内容が「製品=混元、バージョン=Hy4」であり、途切れがない、さらにusageとrequest IDを保存した |
| 課金の確認 | 3.1、3.2 | 経路が通った後にコストを試算し、呼び出し量を増やせるか判断する | 試算値とコンソールの消費ログが項目ごとに一致する |
| 失敗時のトラブルシューティング | 4 | いずれかのステップが失敗したとき、エラーコードとエラー内容から原因を特定する | 設定ミス、権限の問題、レート制限、タイムアウトを区別でき、再試行可否を判断できる |

To Know:Hy4 API 関連の用語
| 用語 | 簡潔な説明 |
|---|---|
| 非ストリーミング(stream=False) | モデルが生成を終えた後に完全な結果をまとめて返すため、内容と使用量を全体として確認しやすい |
| finish_reason | 今回の生成が終了した理由。stop は正常終了、length は長さの上限に達して打ち切られたことを示す |
| usage | レスポンス内のtoken使用量フィールド。よく使われるのはprompt_tokens(入力)とcompletion_tokens(出力) |
| request ID | 単一リクエストの識別子で、ログ内でこの呼び出しを特定するのに使う。すべてのレスポンスに必ず付随するわけではない |
| キャッシュ読み取り | 入力のうちキャッシュにヒットした部分で、別のキャッシュ読み取り価格で課金される |
| グループ(Default/SVIP) | トークンが属するグループで、このトークンがどのモデルを呼び出せるかを決める |
1. Tencent Hunyuan Hy4 API リクエストの準備
1.1 Hy4 モデルとエンドポイントの設定
設定項目を一つずつ確認しましょう。初回呼び出しの失敗の大半は、このステップで発生します。
| 設定項目 | 値 | 説明 |
|---|---|---|
| SDK base_url | https://api.apiyi.com/v1 |
/v1 までを指定します。SDK が自動的に /chat/completions を付加します |
| HTTP エンドポイント | POST https://api.apiyi.com/v1/chat/completions |
SDK を使わず HTTP リクエストを直接送信する場合に使用するアドレスです |
| モデル ID | hy4 |
正式版のモデル名です。小文字のまま記述してください |
| 利用可能なグループ | Default、SVIP | トークンが属するグループに Hy4 が含まれている必要があります |
| 出力方式 | stream=False |
本記事では一貫して非ストリーミングを使用します |
最もよくある間違いは、完全なエンドポイントを base_url に記述してしまうことです。SDK はこのアドレスの後ろにさらに /chat/completions を付加するため、パスが重複し、最終的に 404 が返されます。互換インターフェースの詳細は docs.apiyi.com/api-capabilities/openai/compatible を参照してください。
1.2 OpenAI SDK のインストールと Key の安全な保存
公式 Python SDK のプロジェクト URL は github.com/openai/openai-python です。システムに既存のパッケージバージョンと競合しないよう、仮想環境へのインストールをおすすめします。
python -m venv .venv
source .venv/bin/activate # Windows の場合: .venv\Scripts\activate
python -m pip install openai
Key は api.apiyi.com/token で作成します。作成時は、トークンが属するグループで Hy4 を呼び出せることを確認してください。Key を取得したら、コードファイルには書かず、現在のターミナルの環境変数に設定します。
export APIYI_API_KEY="你的令牌" # Windows PowerShell の場合: $env:APIYI_API_KEY="你的令牌"
Key を管理する際は、次の点に注意してください。
- コードからは
os.environ['APIYI_API_KEY']経由でのみ Key を読み取ります。環境変数が設定されていない場合はgetpassで対話的に入力し、その内容は画面にエコーされません。 .envファイルに Key を保存する場合は、リポジトリへのコミットを避けるため、.gitignoreに追加してください。- スクリーンショット、ログ、チケットなどに Key が含まれる場合は、
sk-***のようなマスクに置き換えてください。
確認: ターミナルで python -c "import openai, os; print(openai.__version__, bool(os.environ.get('APIYI_API_KEY')))" を実行します。バージョン番号と True が出力されれば、このステップは完了です。
2. OpenAI SDK で最初の Hy4 リクエストを送る
2.1 完全な非ストリーミング Python サンプル
この最初のリクエストでは、公開されている一文から製品名とバージョン番号を抽出する、というシンプルな処理だけを行います。顧客データは一切含みません。この設計には2つの利点があります。1つは出力が短くコストが低いこと、もう1つは答えが一意で正誤を判断しやすいことです。
import os
import re
from getpass import getpass
from openai import OpenAI
key = os.environ.get("APIYI_API_KEY") or getpass("输入 APIYI_API_KEY:")
PROMPT = "仅从这句话提取产品和版本:腾讯混元 Hy4 正式版已上线。请只写一行:产品=…;版本=…"
with OpenAI(
base_url="https://api.apiyi.com/v1", # APIYI の OpenAI 互換インターフェース
api_key=key,
timeout=60.0,
max_retries=0, # 自動リトライを無効化。失敗時は人が再送信の要否を判断する
) as client:
result = client.chat.completions.create(
model="hy4",
messages=[{"role": "user", "content": PROMPT}],
stream=False,
)
request_id = getattr(result, "_request_id", None)
print("request_id:", request_id if request_id else "响应未提供")
if not result.choices:
raise SystemExit("未通过:choices 为空,没有返回正文")
choice = result.choices[0]
content = (choice.message.content or "").strip()
print("finish_reason:", choice.finish_reason)
print("content:", content)
usage = getattr(result, "usage", None)
prompt_tokens = getattr(usage, "prompt_tokens", None) if usage else None
completion_tokens = getattr(usage, "completion_tokens", None) if usage else None
print("prompt_tokens:", prompt_tokens if prompt_tokens is not None else "缺失(不按 0 处理)")
print("completion_tokens:", completion_tokens if completion_tokens is not None else "缺失(不按 0 处理)")
def accept(text: str, finish_reason) -> tuple[bool, str]:
if not text:
return False, "正文为空"
if finish_reason == "length":
return False, "输出被截断"
t = re.sub(r"\s+", "", text)
t = t.replace(":", "=").replace(":", "=").replace(";", ";")
prod = re.search(r"产品=([^;\n]+)", t)
ver = re.search(r"版本=([^;\n]+)", t)
if not prod or not ver:
return False, "缺少产品或版本字段"
strip_punct = lambda s: re.sub(r"[。..,,、!!??\"“”'‘’]", "", s)
if "混元" not in strip_punct(prod.group(1)):
return False, f"产品值错误:{prod.group(1)}"
if strip_punct(ver.group(1)) != "Hy4":
return False, f"版本值错误:{ver.group(1)}"
return True, "通过"
ok, reason = accept(content, choice.finish_reason)
print("验收:", reason)
サンプル内のいくつかの設定について補足しておきます。
max_retries=0は SDK の自動リトライを無効にします。第4節で説明しますが、タイムアウトした場合、サーバー側ではすでにリクエストの処理が完了している可能性があり、自動再送信は二重課金につながる恐れがあります。そのため、再試行するかどうかは人が判断する必要があります。with文は、呼び出し終了後に接続をクローズします。- usage フィールドが欠落している場合、コードは明示的に「缺失」と出力し、0 として扱いません。後でコスト計算をする際に費用を見落とさないようにするためです。
レスポンス構造の詳細については docs.apiyi.com/api-capabilities/openai/response-handling を参照してください。
2.2 初回 Hy4 リクエストの受け入れ基準
受け入れ確認では、message.content 内の次の2つのフィールドだけを確認します。製品値に「混元」が含まれていること、バージョン値が「Hy4」であることが条件です。全角・半角のコロンやセミコロン、文末の句読点の違いは許容されます。以下は要件を満たす出力の一例です(これは形式を示すためのサンプルであり、実際のレスポンスではありません):
产品=腾讯混元;版本=Hy4
次のようなケースは、一律に不合格と判定します。「ほぼ同じに見える」という理由で通過させてはいけません:
| 状況 | 判定 | 原因 |
|---|---|---|
| choices が空、または content が空文字列 | 不合格 | 本文を取得できておらず、経路が実際には正常に動作していないことを示す |
finish_reason が length |
不合格 | 出力が切り捨てられ、結果が不完全 |
| バージョンが Hy3 や Hunyuan などの別の値になっている | 不合格 | フィールド値が誤っている |
| 句読点、スペース、コロンの全角・半角のみが異なる | 合格 | 許容される形式の違いに該当 |
受け入れ確認を通過したら、request ID(レスポンスに含まれている場合)、リクエスト時刻、モデル名、prompt_tokens、completion_tokens を記録します。3.2 節で請求内容を照合する際に、これらの情報を使用します。
3. Hy4 API の費用を試算して照合する
3.1 料金表からバッチタスク1回分を試算する
最初のリクエストは入力が非常に短く、コストは無視できる程度なので、それを用いて費用を試算する意味はあまりありません。そこで、サンプルの短いリクエストとは無関係な仮定のシナリオに置き換えます。あるタスクで入力 10 万トークン、すべてキャッシュ未ヒット、出力 2 万トークンとします。入力と出力はそれぞれの単価で計算します。
| 課金項目 | 仮定の使用量 | 単価(100万トークンあたり) | 費用 |
|---|---|---|---|
| キャッシュ未ヒット入力 | 100,000 | $0.85 | $0.085 |
| 出力 | 20,000 | $2.55 | $0.051 |
| 合計 | — | — | $0.136 |
計算式は 0.1 × 0.85 + 0.02 × 2.55 = 0.136 です。試算の際は次の2点に注意してください。
- 出力の単価はキャッシュ未ヒット入力の単価の3倍です。出力量が大きいタスクでは、コストの大部分は出力で決まります。
completion_tokensにモデルの思考部分がすでに含まれている場合は、思考の費用を別途追加しないでください。二重計上になります。
3.2 キャッシュのバケットと実際の使用ログを区別する
「キャッシュ読み取り」は独立した課金項目ですが、レスポンスごとにフィールドの分割方法が同じとは限らないため、結果を正確に保証できる汎用のフィールド名はありません。確実な方法は、まず請求情報で「キャッシュにヒットしたトークンが総入力にすでに含まれているか」を確認することです。
請求情報でキャッシュ部分が総入力に含まれていることが確認できたら、総入力からキャッシュ部分を一度差し引いてから、それぞれを個別に計算します。以下では 3.1 の仮定を引き継ぎ、さらに 10 万入力のうち 4 万がキャッシュにヒットしたと仮定します。
| 課金項目 | 仮定の使用量 | 単価(100万トークンあたり) | 費用 |
|---|---|---|---|
| キャッシュ未ヒット入力 | 60,000 | $0.85 | $0.051 |
| キャッシュ読み取り | 40,000 | $0.045 | $0.0018 |
| 出力 | 20,000 | $2.55 | $0.051 |
| 合計 | — | — | $0.1038 |

試算値はあくまで参考で、最終的には使用ログが基準になります。確認方法は、コンソール api.apiyi.com/log で該当するレコードを絞り込むことです。
- リクエスト時刻で範囲を絞り込む。
- レスポンスに request ID があれば、それを使ってこのリクエストを正確に特定する。
- モデルが
hy4であり、トークンがコードで実際に使用したトークンと一致することを確認する。 - ログの入力・キャッシュ・出力の使用量と請求金額を比較し、試算値と一致するか確認する。
ログの各フィールドの詳しい意味は docs.apiyi.com/faq/log-billing-explained を参照してください。
4. Hy4 API 失敗時のトラブルシューティング
トラブルシューティングでは、まず HTTP ステータスコードを確認し、次にエラー本文に含まれる具体的な情報を読みます。ステータスコードだけを見ると判断を誤りやすく、例えば同じ 429 でも原因はまったく異なる場合があります。2.1 節の元のリクエスト箇所で SDK 例外を捕捉します。接続タイムアウトは APITimeoutError、その他の接続失敗は APIConnectionError を確認します。エラーレスポンスを取得したら、APIStatusError から status_code、request_id、エラー本文を記録します。まず既存のリクエスト結果を判断してからリトライするかどうかを決め、フィードバック前にエラー本文をマスキングしてください。処理の順序は次のとおりです。
| エラー | 優先的に確認する項目 | リトライ可否 |
|---|---|---|
| 401 | Key が正しいか、失効していないか、また base_url が https://api.apiyi.com/v1 になっているか |
設定を修正するまでリトライしない |
| 403 | エラー本文からグループ権限の問題かを判断し、トークンが属するグループに Hy4 が含まれているか確認する | 権限を修正するまでリトライしない |
| 404 | パスに /chat/completions が重複して付加されていないか、モデル名が hy4 かどうか |
設定を修正するまでリトライしない |
| 429 | エラー本文から一時的なレート制限か、クォータ不足かを判断する | 一時的なレート制限は限られた回数でバックオフリトライ可能、クォータ不足は先にチャージするかクォータを調整する必要がある |
| 接続エラー | ネットワーク、プロキシ、DNS が正常か、また base_url のプロトコルとドメインが正しいか | ネットワーク復旧後にリトライ可能 |
| タイムアウト | まず api.apiyi.com/log で時刻を指定して検索し、リクエストがすでに実行されたか確認する |
実行済みなら再送信しない、未実行ならリトライする |
429 とタイムアウトの2つについては特に補足が必要です。
- 429 のバックオフリトライ:一時的なレート制限のみに適用されます。リトライ回数には上限を設け、間隔は毎回徐々に長くします。クォータ不足の場合、何回リトライしても成功しません。
- タイムアウト:クライアントが60秒以内に応答を受信しなかったからといって、サーバー側がそのリクエストを処理していないわけではありません。サーバー側がすでに処理を完了している場合、そのまま再送信すると再度実行され、料金も再度差し引かれます。そのため、先にログを確認し、リクエストが実行されていないことを確かめてから再送信してください。
技術サポートに連絡する必要がある場合は、提出前にエラー本文とログに含まれる Key、顧客データなどの機密情報をマスキングし、ステータスコード、リクエスト時刻、モデル名、request ID を添えてください。エラー情報の保存と提出方法については docs.apiyi.com/api-manual/error-reporting を参照してください。
すべてのトラブルシューティングが完了したら、2.1 のサンプルで再度実行します。一連のフローは、次の3つの条件をすべて満たした場合にのみ合格です。
- 検証関数が「通過」を出力する。
- finish_reason が
lengthではない。 - コンソールログに同一時刻、モデルが
hy4のレコードが見つかり、使用量がローカルに記録した usage と一致する。
