Qwen4-Max APIの使い方:正式版への接続とプレビュー版からの移行
Qwen4-MaxのモデルID、リージョン、課金経路を確認。初回レスポンスを検証し、出力上限とツール履歴を確認してエージェントを移行します。
Qwen4-Maxは正式モデルとして文書化され、API識別子はqwen4-maxです。qwen4-max-previewとは別モデルです。 古い記事にプレビュー契約でしか使えないと書かれている場合は、アプリを設定する前に最新の公式文書を確認してください。
確認日は2026年11月16日です。QwenCloudの直接APIを使い、移行時の判断と簡単なレスポンス検証スクリプトを説明します。文書とローカルの合成レスポンスは確認しましたが、本記事のための有料Qwen4呼び出しやモデルのベンチマークは実施していません。以下は実行用リクエストと合格条件であり、性能測定結果ではありません。
何が変わり、どのモデルを選ぶべきか
公式モデルページ(英語)は現在qwen4-maxを説明し、プレビュー資料は別の識別子を使っています。呼び出す経路で提供されている正確な名称を指定します。無関係なゲートウェイの接頭辞を付けたり、クライアントの表示名をAPI IDだと思い込んだりしないでください。
正式版ではテキスト生成、画像・動画理解、ツール呼び出し、構造化出力が文書化されています。業務用途では、画像を理解することと画像を生成することを区別しましょう。スライドの文章が返ることも、編集可能なプレゼンテーションファイルの作成とは別です。ファイルの作成・実行・受け渡しには、適切なツールと結果を確認する実行基盤が必要です。
| 判断すること | 設定変更前の確認 |
|---|---|
| 正式版とプレビュー版 | 本記事ではqwen4-maxを選び、プレビュー設定は分けて保存する |
| 直接APIとゲートウェイ | 利用するプロバイダー自身のカタログ、認証情報、プロトコルを確認する |
| 従量課金とToken Plan | 課金経路に対応するエンドポイントとキーを使う |
| リージョン | コンソールの地域、キー、エンドポイントを一致させる |
| エージェント移行 | HTTP成功だけでなく、完了したタスクと成果物を検証する |
公式コンテキスト上限は1,000,000トークンです。正式版の文書には、思考なしで最大131,072トークン、または思考と回答の合計で262,144トークンとあります。これらは上限であり、初回リクエストに推奨する既定値ではありません。プレビュー版の古い出力値を正式版の設定へコピーしないでください。
QwenCloudへ直接接続するアカウントを設定する
従量課金APIを使う場合、利用するQwenCloudリージョンでAPIキーを作成または選択します。APIキーの公式手順(英語)とリージョン・エンドポイントの説明(英語)に従い、送信前にアクセス権と課金設定を確認してください。
以下はシンガポールの例です。
Base URL: https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Model: qwen4-max
Protocol: OpenAI-compatible Chat Completions
Token Planのキーは別経路を使います。Token Plan文書(英語)に従い、従量課金用の例にそのまま貼り付けないでください。同じようなプロトコルを使えても、利用権限や請求は共通になりません。
キーはサーバー側の環境変数DASHSCOPE_API_KEYに保存し、リポジトリやスクリーンショットへ含めないようにします。値を表示せず、設定の有無だけ確認できます。
python3 -c 'import os; print("Key configured:", bool(os.environ.get("DASHSCOPE_API_KEY")))'
これは値が存在することだけを確認します。その経路でキーが受け付けられるかは、認証されたリクエストの成功によって確認します。
小さな初回リクエストを送り、結果を確認する
次をrequest.jsonとして保存します。
{
"model": "qwen4-max",
"messages": [
{
"role": "user",
"content": "Return exactly three short checklist items for reviewing an API integration."
}
],
"enable_thinking": false,
"max_completion_tokens": 1024
}
この限定的な接続確認では思考を明示的に無効化します。すべての開発・調査タスクで無効化すべきという意味ではありません。思考ガイド(英語)に各制御の説明があります。トークン上限は出力量の制限であり、長いツール利用ワークフロー全体の費用上限ではありません。
意図した課金アカウントを選んだ後で実行してください。
curl --silent --show-error --fail-with-body \
--max-time 120 \
https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @request.json \
-o response.json
タイムアウト後に自動で同じコマンドを繰り返さないでください。レスポンスが端末に届かなくても、サーバーでは処理済みかもしれません。まずプロバイダーのリクエスト・使用量記録を確認します。この例には意図的に自動再試行ループを入れていません。
次をcheck_response.pyに保存し、python3 check_response.py response.jsonで実行します。
import json
import sys
from pathlib import Path
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
if payload.get("error"):
raise SystemExit("API error: inspect response.json locally.")
choices = payload.get("choices") or []
if not choices:
raise SystemExit("No choices returned; inspect the response format.")
choice = choices[0]
reason = choice.get("finish_reason")
message = choice.get("message") or {}
text = message.get("content")
if reason != "stop":
raise SystemExit(f"Incomplete text check: finish_reason={reason!r}")
if not isinstance(text, str) or not text.strip():
raise SystemExit("No usable final text returned.")
print(text)
print("Usage:", payload.get("usage", "not supplied"))
合格は、空でないテキストと通常の終了マーカーがあることを意味します。要求した三つの項目が実際に含まれるかは別途確認が必要です。 このスクリプトはテキストのみの初回リクエスト専用です。正当なツール呼び出しでも中間結果なので、完成した回答として合格させません。
再確認できるよう、リクエスト日、リージョン、返されたモデル識別子、終了理由、使用量、タスク結果を記録します。ユーザーデータを含む生のレスポンスは非公開で保管してください。
既存の開発・業務エージェントを移行する
移行では、新しい接続先でプロトコルを実行できるかと、エージェントが成果物を完成できるかを別々に判断します。短い挨拶への回答だけでは、プロトコル全体も品質も確認できません。
- 現在の設定を保存する。 プロバイダー、モデル、エンドポイント、クライアント版、ツール権限を記録します。動く設定を全環境で上書きせず、戻せる変更にします。
- 隔離したタスクから始める。 小さなリポジトリや合成した業務文書を使います。テストに通るパッチ、合計が一致するブック、引用を確認できる報告書など、期待する成果物を実行前に決めます。
- クライアント別設定を確認する。 QwenCloudにはQwen Code、Codex、Claude Code用の個別ガイドがあります(いずれも英語)。一つの実行基盤の設定を万能なAPI例として使わないでください。
- ツールの往復を1回検証する。 無害なテストデータを調べ、読み取り専用ツールを呼び、結果を受け取って回答に使わせます。ツール呼び出しIDと履歴が往復後も維持されるかを確認します。
- 成果物を実際に確認する。 生成ファイルを開くかパッチをレビューします。モデルの完了宣言とは別に、数式、引用、テストを確認してください。
- 段階的に広げる。 同じ入力で現行設定と比較し、成功タスクの費用、時間、介入回数を測ります。一つの良い回答だけで本番ワークフローを置き換えないようにします。
合成表計算タスクには、次の英語の検証プロンプトを再利用できます。
Use only the supplied sales.csv. Calculate revenue by month from quantity
and unit_price. Flag missing values rather than inventing them. Deliver:
1. the calculation method;
2. the totals with the source row IDs;
3. a list of excluded rows and reasons.
Do not claim to have created an Excel file unless you actually create and
attach one. Stop and report any tool or file-access failure.
これは実行を提案するテストであり、Qwen4が合格したという主張ではありません。合計を独立して再計算してから、重複行や通貨の違いなど難しい条件を加えてください。
移行結果を崩しやすい二つの細部
出力予算の意味が変わっています。 API互換性のお知らせ(英語)では、Qwen4プレビュー世代以降のmax_tokensは推論と最終回答を合わせた予算とされています。以前は表示テキストに十分だった設定でも、思考を有効にすると挙動が変わる可能性があります。上限を増やす前に完了状態と使用量を確認し、一度に一つだけ設定を変えて費用を測ります。
ツール履歴には表示テキスト以外も必要です。 関数呼び出し文書(英語)と思考ガイドには、アシスタントの推論とツール結果を次のターンへ渡す方法が記載されています。プレーンテキストの会話から履歴を組み直して、プロトコルのフィールドを捨てないでください。一般的な接続パターンはQwenなどの複数ターンのツール呼び出しガイドも参考になりますが、旧モデルの例はQwen4の現行仕様を代替しません。
再試行する前に原因を切り分ける
| 症状 | 最初の確認 | 次の操作 |
|---|---|---|
| 認証拒否 | キーが経路・リージョンと一致するか | キーと接続先を修正し、秘密情報を問い合わせに貼らない |
| モデルが利用不可・見つからない | 正確なID、アカウント権限、プロバイダーカタログ | その経路にqwen4-maxがあるか確認し、別名を推測しない |
| パラメーター拒否 | 他モデルや別プロトコル用の値を送っていないか | 上記の最小リクエストへ戻し、必要項目を一つずつ加える |
| 回答の途中終了・空の最終回答 | 終了理由、推論予算、出力上限 | 予算変更前に使用量と生のレスポンスを確認する |
| ツールループ停止 | アシスタントの呼び出し、対応する結果、推論履歴 | シリアライズしたメッセージを公式の複数ターン例と比較する |
| レート制限 | アカウント枠、同時実行数、レスポンスの案内 | 並列数を減らし、再試行が適切な場合に上限付きバックオフを使う |
| 完了と言うがファイルがない | ツール実行と成果物保存 | ファイルを要求し、内容を確認してから合格にする |
これは診断の分岐であり、Qwen4で全エラーを再現したという報告ではありません。誤ったIDと未対応エンドポイントを区別するには、モデルが見つからない場合のガイド(英語)を参照してください。
費用とOfoxの提供状況は別々に確認する
QwenCloudの現行料金説明(英語)は、リージョン、入力、出力、キャッシュ操作を区別しています。推論トークンは出力料金に含まれます。プレビューのクレジット特典は正式版の共通価格ではなく、Token Planの枠も従量単価ではありません。
キャッシュなしで比較する場合、入力トークン数に該当する入力単価を掛け、出力トークン数に出力単価を掛けた金額を加えます。両単価のトークン単位をそろえ、ツールループ内の全呼び出しを数えてください。キャッシュ利用時はプロバイダーの規則に従って書き込みと読み取りを分類し、同じトークンを二重計上しないようにします。計算結果にはリージョンと価格確認日も添えます。
11月16日のOfox公開カタログにはQwen4-Maxがありませんでした。 そのため、上記のQwenCloud直接接続はOfoxの接続手順ではありません。今すぐOfoxの既存経路が必要なら、Qwen3.8 Max 0902モデルページを確認し、Qwen4の別名ではなく異なるモデルとして評価してください。
OfoxへのリクエストにはAPIキー認証とエラー処理の文書を使います。それらの認証情報や規則でQwenCloudへ認証することはできません。ゲートウェイへ設定を移す前に、新モデルの実際の掲載情報と対応プロトコルを確認してください。
よくある質問
- Qwen4-Maxはまだプレビュー限定ですか?
- いいえ。現行の公式文書にはqwen4-maxが掲載され、従量課金APIとToken Planが案内されています。qwen4-max-previewは別の識別子です。プレビューの条件を正式版に当てはめず、それぞれの条件を確認してください。
- Ofox経由でQwen4-Maxを呼べますか?
- 2026年11月16日の公開カタログ確認ではQwen4-Maxは見つかりませんでした。本記事はQwenCloudへの直接接続を扱い、Ofoxでの提供を主張しません。
- 100万トークンのコンテキストなら100万トークン出力できますか?
- いいえ。正式版は1,000,000トークンのコンテキストを持ちますが、入出力には個別の制限があります。思考なしの最大出力は131,072、思考と回答の合計は最大262,144トークンです。


