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"))

合格は、空でないテキストと通常の終了マーカーがあることを意味します。要求した三つの項目が実際に含まれるかは別途確認が必要です。 このスクリプトはテキストのみの初回リクエスト専用です。正当なツール呼び出しでも中間結果なので、完成した回答として合格させません。

再確認できるよう、リクエスト日、リージョン、返されたモデル識別子、終了理由、使用量、タスク結果を記録します。ユーザーデータを含む生のレスポンスは非公開で保管してください。

既存の開発・業務エージェントを移行する

移行では、新しい接続先でプロトコルを実行できるかと、エージェントが成果物を完成できるかを別々に判断します。短い挨拶への回答だけでは、プロトコル全体も品質も確認できません。

  1. 現在の設定を保存する。 プロバイダー、モデル、エンドポイント、クライアント版、ツール権限を記録します。動く設定を全環境で上書きせず、戻せる変更にします。
  2. 隔離したタスクから始める。 小さなリポジトリや合成した業務文書を使います。テストに通るパッチ、合計が一致するブック、引用を確認できる報告書など、期待する成果物を実行前に決めます。
  3. クライアント別設定を確認する。 QwenCloudにはQwen Code、Codex、Claude Code用の個別ガイドがあります(いずれも英語)。一つの実行基盤の設定を万能なAPI例として使わないでください。
  4. ツールの往復を1回検証する。 無害なテストデータを調べ、読み取り専用ツールを呼び、結果を受け取って回答に使わせます。ツール呼び出しIDと履歴が往復後も維持されるかを確認します。
  5. 成果物を実際に確認する。 生成ファイルを開くかパッチをレビューします。モデルの完了宣言とは別に、数式、引用、テストを確認してください。
  6. 段階的に広げる。 同じ入力で現行設定と比較し、成功タスクの費用、時間、介入回数を測ります。一つの良い回答だけで本番ワークフローを置き換えないようにします。

合成表計算タスクには、次の英語の検証プロンプトを再利用できます。

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トークンです。