TencentのHy3は、Novita AI上でモデルID tencent/hy3、OpenAI互換の chat/completions エンドポイント、256Kコンテキストウィンドウ、関数呼び出し、構造化出力、および3つの推論モードをサポートして利用可能です。このクイックスタートでは、開発者向けのセットアップ手順を解説します。クライアントの設定、最初のリクエスト送信、関数呼び出しの使用、推論の有効化、そして構築前のレート制限の理解までをカバーします。
このクイックスタートを活用すべきタイミング
追加のコードを書く前に、Hy3への動作確認済みのリクエストが必要な場合にこのガイドを参照してください。モデルIDの選択、認証、テストリクエストの送信、そして必要に応じて関数呼び出しや推論への拡張という実用的な流れを提供します。
Hy3のアーキテクチャ（総パラメータ295B、アクティブパラメータ21BのMoE）は、大規模運用における品質と効率のバランスを考慮して設計されています。以下のようなニーズに適しています。
- 長文コンテキストのドキュメント処理（256Kウィンドウは1回の呼び出しで約20万語を処理可能）。
- 大規模なアクティブパラメータ予算を活用する多ターン対話。
- ツール呼び出しと信頼性の高い引数フォーマットが重要なエージェンティックタスク。
- チャンク化せずに大規模コードベースを扱うコーディング支援。
このガイドは、Novita AIを介したAPI統合パスのみを対象としています。セルフホスティング、ファインチューニング、他の推論バックエンドへの移植については扱いません。
ステップ1：Novita APIキーを取得する
Novita AIアカウントを作成し、コンソールのAPIキーセクションに移動します。キーを生成し、環境変数に保存します。クライアントサイドコード、フロントエンドバンドル、公開リポジトリには絶対に含めないでください。
export NOVITA_API_KEY="your_api_key"
すでにOpenAI Python SDKや他のプロジェクトでOpenAI互換クライアントを使用している場合、セットアップは同じです。ベースURLとモデル名を変更するだけで、他に変更はありません。
ステップ2：モデルIDとエンドポイントを確認する
設定に必要なのは以下の3つの値だけです。
| 項目 | 値 |
|---|---|
| APIキー | Novita AI APIキー（環境変数に保存） |
| OpenAI互換ベースURL | https://api.novita.ai/openai |
| チャット完了エンドポイント | POST https://api.novita.ai/openai/v1/chat/completions |
| モデルID | tencent/hy3 |
すべてのAPI呼び出しで tencent/hy3 を使用してください。ユーザー向けUIやドキュメントでは、表示名「Hy3」を使用します。
Novita AIドキュメントインデックス にOpenAI互換ベースURLが記載されており、チャット完了APIリファレンス に完全なリクエストおよびレスポンス形式が文書化されています。
ステップ3：価格、制限、モデルの詳細を確認する
Novita AIのHy3モデルページ からの現在の値：
| フィールド | 値 |
|---|---|
| 表示名 | Hy3 |
| APIモデルID | tencent/hy3 |
| モデルシリーズ | Hunyuan |
| アーキテクチャ | MoE、総パラメータ295B / アクティブ21B |
| エンドポイント | chat/completions |
| 入力モダリティ | テキスト |
| 出力モダリティ | テキスト |
| コンテキストウィンドウ | 262,144 トークン |
| 最大出力トークン数 | 262,144 トークン |
| 機能 | サーバーレス、関数呼び出し、構造化出力、推論 |
| 入力価格 | 記載：$0 / Mトークン（現在のレートはモデルページで確認） |
| 出力価格 | 記載：$0 / Mトークン（現在のレートはモデルページで確認） |
レート制限はアカウント階層（T1～T5）によって異なり、1分あたりのリクエスト数（RPM）と1分あたりのトークン数（TPM）で測定されます。現在の階層しきい値と制限は、Novita AIレート制限ドキュメント に記載されています。
価格とレート制限は変更される可能性があります。コスト見積もりを確定する前に、Hy3モデルページ と Novita AI価格ページ を確認してください。
ステップ4：最初のリクエストを送信する
まずはシンプルなテキストリクエストで、認証、モデルルーティング、レスポンス解析を確認します。プロンプトは短くして、接続性のテストに集中し、出力品質は問いません。
cURLの例
curl "https://api.novita.ai/openai/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${NOVITA_API_KEY}" \
-d '{
"model": "tencent/hy3",
"messages": [
{
"role": "system",
"content": "You are a concise technical assistant."
},
{
"role": "user",
"content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences."
}
],
"max_tokens": 256,
"temperature": 0.3
}'
成功したレスポンスは、標準的なチャット完了形式を返します。choices 配列、content を持つメッセージ、モデルと作成日時のメタデータ、そしてプロンプト、完了、合計トークン数を含む usage オブジェクトです。
このスモークテストで以下を確認します。
- APIキーが有効で、認証ヘッダーの形式が正しいこと。
- モデルID
tencent/hy3が受け入れられ、404やモデル未検出エラーが発生しないこと。 - クライアントが
choices[0].message.contentを解析できること。 - トークン使用量が記録され、最初のリクエストからコストを監視できること。
Pythonの例
OpenAI Python SDKは、ベースURLを設定することでNovita AIで動作します。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
response = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{
"role": "user",
"content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences.",
},
],
max_tokens=256,
temperature=0.3,
)
print(response.choices[0].message.content)
print("Tokens used:", response.usage.total_tokens)
ステップ5：レスポンスを読み取る
レスポンスは標準のOpenAIチャット完了形式に従います。
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1751000000,
"model": "tencent/hy3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "MoE models activate only a fraction of their total parameters..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 52,
"completion_tokens": 80,
"total_tokens": 132
}
}
finish_reason フィールドは、生成が停止した理由を示します。stop はモデルが自然な終了点に達したことを意味します。length は max_tokens に達したことを意味します。短いプロンプトで length が表示された場合は、max_tokens を増やすかプロンプトを削減してください。
主要なパラメータ
| パラメータ | 型 | 効果 |
|---|---|---|
model |
文字列 | tencent/hy3 である必要があります |
messages |
配列 | 会話履歴。system、user、assistant ロールをサポートします。 |
max_tokens |
整数 | 出力トークンの上限。明示的に設定してください。デフォルトはクライアントによって異なる場合があります。 |
temperature |
浮動小数点数（0～2） | 値が低いほど決定論的な出力になります。コードや事実タスクには0.1～0.3、クリエイティブまたは多様な出力には0.7～1.0を使用します。 |
top_p |
浮動小数点数（0～1） | サンプリングのためのtemperatureの代替。両方を同時に設定することは避けてください。 |
stream |
ブール値 | true に設定すると、トークンをストリームとして受信します。クライアント側でのサーバー送信イベント処理が必要です。 |
tools |
配列 | 関数呼び出しのためのツール定義。以下の関数呼び出しセクションを参照してください。 |
tool_choice |
文字列またはオブジェクト | モデルが呼び出すツールを制御します。"auto" はモデルに決定させます。 |
長文コンテキストのワークロードでは、Hy3は最大262,144の入力トークンをサポートします。大規模なドキュメントや長い会話履歴を処理する場合は、呼び出しごとのトークン使用量を予算化し、累積コストを監視してください。
関数呼び出し
Hy3は tools パラメータを通じて関数呼び出しをサポートしています。モデルに散文ではなく構造化された引数を返させたい場合（リクエストを特定のアクションにルーティングする、ユーザー入力を型付きフィールドに解析する、マルチステップワークフローを駆動するなど）に使用します。
import os
import json
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
tools = [
{
"type": "function",
"function": {
"name": "search_knowledge_base",
"description": "Search a product knowledge base for answers to customer queries.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The customer's question or topic to search for.",
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return. Default is 5.",
},
},
"required": ["query"],
},
},
}
]
response = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "You are a customer support assistant. Use the search tool to find relevant answers."},
{
"role": "user",
"content": "What is your return policy for electronics purchased in the last 30 days?",
},
],
tools=tools,
tool_choice="auto",
temperature=0.1,
)
message = response.choices[0].message
if message.tool_calls:
for call in message.tool_calls:
print(f"Tool: {call.function.name}")
args = json.loads(call.function.arguments)
print(f"Arguments: {args}")
else:
print(message.content)
モデルがツール呼び出しを返した場合、アプリケーションが関数を実行し、結果を会話に送り返します。
# After executing your search function, send the result back
tool_result = "Returns accepted within 30 days with original receipt. Electronics must be unopened."
follow_up = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "You are a customer support assistant."},
{"role": "user", "content": "What is your return policy for electronics purchased in the last 30 days?"},
message, # the assistant's tool call message
{
"role": "tool",
"tool_call_id": message.tool_calls[0].id,
"content": tool_result,
},
],
temperature=0.1,
)
print(follow_up.choices[0].message.content)
)
本番トラフィックをルーティングする前に、代表的なクエリでツールスキーマをテストしてください。関数引数の抽出品質は、各パラメータとその期待値をどれだけ明確に記述するかに依存します。
## 推論モード
Hy3は、Novita AIのモデルページでサポートされている機能として推論を挙げています。推論可能なモデルは、最終的な回答を生成する前に問題を思考するため、複雑な多段階問題（コードデバッグ、多段階数学、長文ドキュメント分析、計画タスクなど）の出力品質を向上させることができます。
Novita AIのチャット完了APIは、一部のモデル向けに推論関連パラメータ（`separate_reasoning`、`enable_thinking`）をサポートしています。これらのパラメータが `tencent/hy3` で受け入れられるかどうか、および正確なリクエスト形式は、現在のNovitaドキュメントでは確認されていません。Hy3で推論動作を本番ワークフローに組み込む前に、テストコールを実行し、レスポンスに `choices[0].message` 内の `reasoning_content` フィールドが含まれているかどうかを確認してください。
確認済みのパラメータ名とサポートされているモデルIDについては、[Novita AIチャット完了APIリファレンス](https://novita.ai/docs/api-reference/model-apis-llm-create-chat-completion) および [推論モデルガイド](https://novita.ai/docs/guides/llm-reasoning) を参照してください。
## 長文コンテキストの使用法
Hy3の256Kコンテキストウィンドウは、1回の呼び出しで大量のテキストを保持する必要があるタスクにおいて実用的な利点となります。これが重要なユースケースは以下の通りです。
- **ドキュメント分析**: 契約書、研究論文、仕様書全体をコンテキストとして送信し、チャンク化せずにターゲットを絞った質問をする。
- **コードベースレビュー**: 大きなファイルや複数の関連ファイルを渡し、アーキテクチャの観察、バグパターン、リファクタリングの提案を依頼する。
- **長い会話履歴**: 多くのターンが蓄積されるエージェンティックワークフローは、要約や切り詰めが必要になる前に、より長くコンテキスト内に留まることができる。
長文コンテキストの呼び出しでは、期待される出力長に基づいて `max_tokens` を明示的に設定してください。200Kトークンの入力を送信しながら出力トークン予算をデフォルトのままにすると、コンテキスト予算を無駄にし、レスポンスが途中で切れる可能性があります。
```python
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
with open("large_document.txt") as f:
document_text = f.read()
response = client.chat.completions.create(
model="tencent/hy3",
messages=[
{
"role": "system",
"content": "You are a document analysis assistant. Provide specific, referenced answers.",
},
{
"role": "user",
"content": f"Here is the document:\n\n{document_text}\n\nSummarize the key obligations and deadlines in this document.",
},
],
max_tokens=1024,
temperature=0.2,
)
print(response.choices[0].message.content)
)
レスポンス内の `usage.prompt_tokens` を監視して、入力が消費するトークン数を追跡してください。同じシステムプロンプトやドキュメントプリアンブルを繰り返し送信するワークロードでは、レート制限とコスト計画はドキュメントの文字数だけでなく、実際のプロンプトトークン数に依存します。
## トラブルシューティング
**401 Unauthorized**: APIキーが見つからない、期限切れ、または形式が正しくありません。`Authorization` ヘッダーが `Bearer <your_key>` のように、スペースと余分な文字がないことを確認してください。
**404 またはモデル未検出**: モデルIDが間違っています。正確な文字列 `tencent/hy3` がNovita AIモデルページに表示されているIDと一致することを確認してください。モデルIDは大文字と小文字を区別します。
**429 レート制限**: お使いの階層の1分あたりのリクエスト数またはトークン数を超えました。指数バックオフ付きのリトライロジックを追加するか、ワークロードで一貫して必要とする場合は上位階層をリクエストしてください。
**`finish_reason: length`**: レスポンスが `max_tokens` に達したため途中で切れました。より長い出力が必要な場合は `max_tokens` の値を増やしてください。ただし、出力トークンはコストとレイテンシに影響することを覚えておいてください。
**最初のレスポンスが遅い**: 大規模なモデルデプロイメントでは、最初のリクエスト時に短いコールドスタートレイテンシが発生する可能性があります。同じエンドポイントへの後続のリクエストは通常、より高速です。レイテンシが厳しい要件である場合は、本番稼働前に対象の同時実行レベルでスループットをテストしてください。
**ツール呼び出しが予期しない引数を返す**: ツールスキーマを見直してください。各パラメータに具体的な説明を追加し、descriptionフィールドに例を含め、必須フィールドを明示的に列挙してください。まずは簡略化したスキーマでテストし、その後複雑性を追加してください。
## よくある質問
### Hy3はNovita AIで利用できますか？
はい。Novita AIはHy3をAPIモデルID `tencent/hy3` のサーバーレスLLMとしてリストしています。
### 正しいモデルIDは何ですか？
すべてのAPI呼び出しで `tencent/hy3` を使用してください。ユーザー向けテキストでは「Hy3」を使用します。
### どのエンドポイントを使用すべきですか？
OpenAI互換のチャット完了エンドポイント `POST https://api.novita.ai/openai/v1/chat/completions` を使用してください。OpenAI SDKを使用する場合は、ベースURLを `https://api.novita.ai/openai` に設定します。
### コンテキストウィンドウのサイズは？
Hy3は、Novita AIモデルページに記載されているとおり、262,144トークンのコンテキストウィンドウと最大262,144の出力トークンをサポートしています。
### Hy3は関数呼び出しをサポートしていますか？
はい。Hy3はチャット完了リクエストの `tools` パラメータを通じて関数呼び出しをサポートしています。Novitaは関数呼び出しと構造化出力をサポートされている機能として挙げています。
### Hy3は推論をサポートしていますか？
推論はNovita AIモデルページで機能として挙げられています。`tencent/hy3` で推論を有効にするための具体的なリクエストパラメータは、現在のNovitaドキュメントでは確認されていません。[Novita AIチャット完了APIリファレンス](https://novita.ai/docs/api-reference/model-apis-llm-create-chat-completion) を確認し、テストコールを実行してパラメータ形式を検証してから、推論動作を本番環境に組み込んでください。
### Hy3はどのような入力を受け付けますか？
Hy3はテキスト入力のみを受け付けます。Novita AIモデルページには画像やビデオのモダリティは記載されていません。
### Hy3のアーキテクチャは？
Hy3はMoE（Mixture of Experts）アーキテクチャを採用しており、総パラメータ数295B、フォワードパスあたりのアクティブパラメータ数21Bです。これにより、同等の品質の高密度モデルと比較して、低い計算コストで大規模コンテキストリクエストを処理できます。
### より高いレート制限を得るには？
レート制限はアカウント階層によって異なります。現在の階層しきい値と制限は [Novita AIレート制限ドキュメント](https://novita.ai/docs/guides/llm-rate-limits) に記載されています。アップグレードオプションについてはNovita AIサポートにお問い合わせください。
## おすすめ記事
- [Novita AIでの関数呼び出しと構造化出力](/function-calling-and-structured-outputs/)
- [LangChainとNovita AIのLLM APIを使用したディープサーチエージェンティックワークフローの開発方法](/how-to-develop-a-deep-search-agentic-workflow-with-langchain-and-novita-ais-llm-api/)
- [Novita AI上のHunyuan Image 3 API：テキストから画像生成ガイド](/hunyuan-image-3-api-on-novita-ai/)
