コーディング向けDeepSeek V4 API：deepseek-v4-proとdeepseek-v4-flashのルーティング

コーディングセッションのすべてのステップを1つのモデルに送信するのは最も簡単なルーティングポリシーですが、通常は最もコストがかかる方法でもあります。本チュートリアルでは、deepseek-v4-proとdeepseek-v4-flashの間で作業を分割し、TokenLab上でコーディングにDeepSeek V4 APIを使用する方法を解説します。以下の内容は、2026年10月3日にライブAPIから読み取った両モデルのレコード、およびTokenLabのドキュメントに基づいています。比較表、コスト見積もりの計算例、ツール呼び出しリクエスト、リトライおよびフォールバックのコード、そしてプリフライトチェックを提供します。

重要なポイント

• 両モデルとも、入力制限1,000,000トークン、出力制限384,000トークン、および同じ3つのリクエストフォーマットをリストしています。主な違いは価格です。
• 定価ベースでは、deepseek-v4-proはdeepseek-v4-flashと比較して、入力トークンあたり4.4倍、出力トークンあたり3.3倍のコストがかかります。
• 20回の呼び出しを行う例では、4回をpro、16回をflashにルーティングした場合、オフピーク時のコストは約0.18ドルです。すべてをproに送信すると約0.46ドルかかります。
• 429エラーはRetry-Afterに従ってリトライしてください。500～504エラーはretryableがtrueの場合のみリトライしてください。400、401、402、403、404、または413は、そのままの状態でリトライしないでください。
• カタログにはdeepseek-v4.1-flashがアクティブとして記載されています。deepseek-v4-proもdeepseek-v4-flashも、代替モデルを指定していません。
• ルーティングを行う前に、GET /v1/models/:modelから制限、フォーマット、価格を読み取ってください。コピーした表をハードコードしないでください。

コーディング向けDeepSeek V4 API：カタログの内容

2026年10月3日に両方のレコードを取得しました。以下の表はそれらを並べて比較したものです。価格は100万トークンあたりの米ドル（USD）であり、カタログの価格設定は2026年10月2日 16:53:30.068Zに最終更新されました。

項目	deepseek-v4-pro	deepseek-v4-flash	ソース（2026-10-03観測）
コンテキスト制限（最大入力トークン）	1,000,000	1,000,000	pro, flash
出力制限（最大出力トークン）	384,000	384,000	pro, flash
対応リクエストフォーマット	anthropic_messages, openai_chat_completions, openai_responses	anthropic_messages, openai_chat_completions, openai_responses	pro, flash
機能	json-mode, prompt-cache, tool-use	json-mode, prompt-cache, tool-use	pro, flash
オフピーク入力	$0.66	$0.15	pro, flash
オフピーク出力	$1.98	$0.60	pro, flash
オフピークキャッシュ読み取り	$0.022	$0.003	pro, flash
オフピークキャッシュ書き込み	$0.66	記載なし	pro, flash
ピーク入力	$1.32	$0.30	pro, flash
ピーク出力	$3.96	$1.20	pro, flash
ピークキャッシュ読み取り	$0.044	$0.006	pro, flash
ライフサイクルステージ	アクティブ、2026-04-24リリース	アクティブ、2026-04-24リリース	pro, flash

各レコードのデフォルト価格ブロックはオフピークの項目と一致しています。ピーク時間はレコードによって異なります。deepseek-v4-proの場合、ピーク価格は北京時間の09:00～12:00および14:00～18:00に適用されます。deepseek-v4-flashの場合、レコードにはピーク時間帯は平日（中国の祝日を除く）に適用されると記載されています。オフピークには週末と祝日が含まれるとされていますが、具体的な時間は記載されていません。flashの時間帯に合わせて予算を組む前に、価格設定エンドポイントを確認してください。

ライフサイクルと新しいDeepSeekモデル

両方のレコードがlifecycle stage activeを示しており、replacement model、deprecated_at、retired_atはいずれも空です。したがって、カタログ上ではどちらのモデルも削除予定はなく、後継モデルも指定されていません。

カタログにはdeepseek-v4.1-flashも記載されています。2026年10月3日に観測されたそのレコードはアクティブであり、リリース日や代替モデルの指定はありません。制限、フォーマット、定価はdeepseek-v4-flashと同じです。機能リストにreasoningとvisionが追加されており、オフピーク時のキャッシュ書き込み価格は0.15ドルと表示されています。

これは別のモデルIDであるため、本記事では対象外とします。deepseek-v4.1-flashを導入する前に、ご自身のタスクでテストすることをお勧めします。カタログにはdeepseek-v4-flash-vision-expも記載されていますが、そのレコードは読み取っていません。必要な場合はModelsページで確認してください。

タスク別のdeepseek-v4-proとdeepseek-v4-flashのルーティング

5つのモジュールにわたる変更を計画し、編集を行い、12個のテストスタブを生成するエージェントセッションを想像してください。最初のステップには最も多くのコンテキストと注意が必要です。最後のステップは反復的で、やり直しのコストも低いです。カタログでは品質の境界線がどこにあるかまでは分かりません。2026年10月3日に観測されたTokenLabのコーディングエージェントモデルに関するガイドでは、リーダーボードの結果は、モデルが独自の指示やツールにどのように従うかを予測するものではないと述べています。

私たちの初期ヒューリスティックは、高価なモデルはファイル横断的な作業でそのコストに見合う価値を発揮するという仮定に基づいています。これは発見ではなく、テストすべき仮説として扱ってください：

+-------------------------------------------------------------+
|                      受信タスク                             |
+-------------------------------------------------------------+
                               |
         [タスクに複数ファイルのコンテキスト、
          後方互換性、またはセキュリティレビューが含まれるか？]
                               |
               +---------------+---------------+
               |                               |
             [はい]                           [いいえ]
               |                               |
               v                               v
       deepseek-v4-pro                 deepseek-v4-flash

ステップをdeepseek-v4-proに回すべき基準：

• 複数のインポートされたファイルにわたるロジックの変更。
• セキュリティまたは脆弱性の評価。
• パブリックインターフェースにおける厳格な後方互換性。
• ターンアラウンドよりも正確性が重視されるマルチターン作業。

スタンドアロンのテスト足場、スキーマのフォーマット、ドキュメント文字列、構文補完はdeepseek-v4-flashに回します。

ヒューリスティックをテストするには、同じガイドに従ってください。各モデルに同じリポジトリ状態、指示、ツール、制限時間を与えます。その後、正確性、テストの通過率、不要な変更、合計トークン数、最終コスト、および人間が介入する必要があった頻度を比較します。モデルによってレビューは優れていても実装が不十分な場合があるため、タスクタイプごとに結果を記録してください。

コーディングエージェントループのコスト見積もり

エージェントは呼び出しのたびに指示、履歴、コード、ツールの結果を再送信します。2026年10月3日に観測されたコストガイドでは、長いセッションは単一のチャットリクエストよりもはるかにコストがかかる可能性があると指摘されています。以下では定価から計算を行いました。結果は測定された請求額ではなく、見積もりです。

前提条件（測定値ではなく想定）： 20回のモデル呼び出しループ。各呼び出しで30,000入力トークン、1,500出力トークンを使用。合計で600,000入力トークン、30,000出力トークンとなります。

計算式は入力トークン数 / 100万 × 入力単価 + 出力トークン数 / 100万 × 出力単価です。価格は上記の表から引用しています。

20回すべてをdeepseek-v4-proで呼び出す場合：

• オフピーク：0.6 × $0.66 = $0.396（入力）、0.03 × $1.98 = $0.0594（出力）、合計 $0.4554。
• ピーク：0.6 × $1.32 = $0.792（入力）、0.03 × $3.96 = $0.1188（出力）、合計 $0.9108。

20回すべてをdeepseek-v4-flashで呼び出す場合：

• オフピーク：0.6 × $0.15 = $0.09（入力）、0.03 × $0.60 = $0.018（出力）、合計 $0.108。
• ピーク：0.6 × $0.30 = $0.18（入力）、0.03 × $1.20 = $0.036（出力）、合計 $0.216。

混合：4回をpro、16回をflashで呼び出す場合。 Proは120,000入力トークンと6,000出力トークンを消費。Flashは480,000入力トークンと24,000出力トークンを消費。

• オフピーク：proは0.12 × $0.66 + 0.006 × $1.98 = $0.0792 + $0.01188 = $0.09108。Flashは0.48 × $0.15 + 0.024 × $0.60 = $0.072 + $0.0144 = $0.0864。合計は$0.17748。
• ピーク：proは0.12 × $1.32 + 0.006 × $3.96 = $0.1584 + $0.02376 = $0.18216。Flashは0.48 × $0.30 + 0.024 × $1.20 = $0.144 + $0.0288 = $0.1728。合計は$0.35496。

シナリオ	オフピーク見積もり	ピーク見積もり
20回すべて deepseek-v4-pro	$0.4554	$0.9108
20回すべて deepseek-v4-flash	$0.1080	$0.2160
4 pro + 16 flash	$0.1775	$0.3550

見積もりは2026年10月3日に観測された定価に基づきます（pro, flash）。

キャッシュバリアント（オフピーク、想定：入力トークンの80%がキャッシュ読み取り）。 つまり、1ループあたり480,000キャッシュ読み取りトークン、120,000非キャッシュトークンとなります。

• Pro：0.48 × $0.022 = $0.01056、0.12 × $0.66 = $0.0792、出力 $0.0594、合計 $0.14916。
• Flash：0.48 × $0.003 = $0.00144、0.12 × $0.15 = $0.018、出力 $0.018、合計 $0.03744。

このバリアントでは、非キャッシュトークンは通常の入力価格で請求され、flashのキャッシュ書き込み料金（レコードに記載なし）は無視しています。この割引を当てにする前に、レスポンスまたは使用状況（Usage）でキャッシュされたトークン数を確認してください。請求ガイドでは、リトライによってコストが積み重なるため、トークンあたりの最低価格が必ずしもタスク完了あたりの最低コストになるとは限らないと警告しています。

コーディングエージェント向けのツール呼び出しリクエスト

両方のレコードがtool-useをリストしており、どちらもopenai_chat_completionsを受け入れます。以下のリクエストでは、ツール呼び出しガイド（2026年10月3日観測）のフィールドのみを使用しています：model、messages、およびtype: "function"を指定したtools。レスポンスの長さを制限する方法として請求ガイドに記載されているmax_tokensを追加しました。tool_choiceはResponsesフォーマットでのみ文書化されているため、除外しました。

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "max_tokens": 2000,
    "messages": [
      {"role": "system", "content": "You are a software engineering assistant."},
      {"role": "user", "content": "The pagination test in tests/test_api.py fails. Find the cause."}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "read_file",
          "description": "Read a file from the repository",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "run_tests",
          "description": "Run the test suite for one path",
          "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"]
          }
        }
      }
    ]
  }'

モデルはtool_calls内に関数名と引数を返します。バックエンドでツールを実行し、ループは以下の5つのステップで進行します：

1. メッセージとツール定義を送信する。
2. tool_callsのレスポンスを読み取る。
3. 独自のバックエンドでツールを実行する。
4. 同じAPIフォーマットでツールの結果を追加する。
5. モデルが最終回答を返すまで継続する。

ガイドにはツール結果メッセージの形状がインラインで示されていません。推測するのではなく、Create Chat Completionリファレンス（/api-reference/chat/create-completion）から取得してください。

呼び出しを実行する前に、引数を検証し、独自の権限チェックを適用してください。クライアントのリトライによって同じツール呼び出しが繰り返される可能性があるため、実行はべき等（idempotent）にしてください。フォーマットによってツール状態の表現が異なるため、やり取り全体で1つのAPIフォーマットを維持してください。

2つのモデル間のリトライ、バックオフ、フォールバック

エラーガイドとレート制限ガイド（いずれも2026年10月3日観測）がポリシーを定めています。HTTPステータスとcodeで分岐し、messageで分岐しないでください。

ステータス	同じリクエストを繰り返すか？	アクション
400, 401, 402, 403, 404, 413	いいえ	リクエスト、キー、残高、権限、または入力を修正する
429	はい	Retry-Afterを待つ。存在しない場合はジッター付き指数バックオフを使用
500–504	retryableがtrueの場合のみ	retry_afterを尊重し、試行回数を制限する
レスポンス前に接続切断	場合による	ツール呼び出しが副作用を繰り返す可能性がある場合は注意してリトライする
出力到着後にストリーム中断	いいえ	不完全として扱う。リトライすると異なる出力や2回目の課金が発生する可能性がある

2つのケースには特別な注意が必要です。503 all_channels_failedまたは503 delivery_tier_unavailableは常に一時的とは限りません。retryableがfalseでretry_afterがない場合、リクエストを繰り返さないでください。別のモデルを選択する前にGET /v1/modelsを確認してください。また、context_length_exceededは、両モデルとも同じ1,000,000トークンの入力制限であるため、モデルを切り替えても解決しません。

以下のコードはそのポリシーを適用しています。SDKが勝手にリトライしないようmax_retries=0に設定しています。各モデルに4回の試行を行い、最初のモデルでリトライ可能なエラーを使い果たした後にのみフォールバックを実行します。

import os
import random
import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

FALLBACK = {
    "deepseek-v4-pro": "deepseek-v4-flash",
    "deepseek-v4-flash": "deepseek-v4-pro",
}

def error_fields(exc):
    body = getattr(exc, "body", None)
    if isinstance(body, dict):
        return body.get("error", body)
    return {}

def backoff(attempt):
    return min(30, 2 ** attempt + random.random())

def retry_delay(exc, attempt):
    """待機秒数。リクエストを繰り返してはいけない場合はNoneを返す。"""
    if isinstance(exc, APIConnectionError):
        return backoff(attempt)
    fields = error_fields(exc)
    header = exc.response.headers.get("Retry-After")
    if exc.status_code == 429:
        return float(header) if header else backoff(attempt)
    if exc.status_code >= 500 and fields.get("retryable") is True:
        wait = fields.get("retry_after") or header
        return float(wait) if wait else backoff(attempt)
    return None

def chat_with_fallback(model, messages, tools=None, attempts=4):
    last_exc = None
    for candidate in (model, FALLBACK[model]):
        kwargs = {"model": candidate, "messages": messages}
        if tools:
            kwargs["tools"] = tools
        for attempt in range(attempts):
            try:
                return candidate, client.chat.completions.create(**kwargs)
            except (APIStatusError, APIConnectionError) as exc:
                delay = retry_delay(exc, attempt)
                if delay is None:
                    raise  # 4xxまたはリトライ不可の5xx：繰り返しやフォールバックを行わない
                last_exc = exc
                if attempt < attempts - 1:
                    time.sleep(delay)
        print(f"{candidate} exhausted retries, trying {FALLBACK[candidate]}")
    raise last_exc

def pick_model(is_complex):
    return "deepseek-v4-pro" if is_complex else "deepseek-v4-flash"

used, response = chat_with_fallback(
    pick_model(is_complex=False),
    [{"role": "user", "content": "Write a pytest case: an empty list returns 0 for sum_items()."}],
)
print(used, response.choices[0].message.content)

どのモデルが回答したかを必ずログに記録してください。コーディングエージェントガイドでは、フォールバックによって価格、コンテキスト制限、ツールフォーマット、出力スタイルが変わる可能性があるため、モデルが変更されたことをユーザーに通知するよう警告しています。FlashからProへのフォールバックは定価ベースで入力コストが約4倍になるため、アラートを出してください。サポートが障害を追跡できるよう、呼び出しごとにレスポンスヘッダーからリクエストIDを保存してください。

ルーティング前に制限、フォーマット、価格を読み取る

2026年10月3日に観測されたGet a Modelリファレンスは、GET /v1/models/:modelについて説明しています。レスポンスにはcapabilities、pricing、max_input_tokens、max_output_tokens、accepted_request_formats、lifecycleを含むtokenlabオブジェクトが含まれます。不明なモデルは404 model_not_foundを返します。請求ガイドでは、現在の価格についてGET /v1/models/:model/pricingを参照するよう指示されています。

import json
import urllib.request

def read_model(model_id):
    url = f"https://api.tokenlab.sh/v1/models/{model_id}"
    with urllib.request.urlopen(url, timeout=10) as resp:
        meta = json.load(resp)["tokenlab"]
    return {
        "max_input_tokens": meta.get("max_input_tokens"),
        "max_output_tokens": meta.get("max_output_tokens"),
        "formats": meta.get("accepted_request_formats"),
        "capabilities": meta.get("capabilities"),
        "lifecycle": meta.get("lifecycle"),
        "pricing": meta.get("pricing"),
    }

def preflight(model_id, input_tokens):
    info = read_model(model_id)
    problems = []
    if "openai_chat_completions" not in (info["formats"] or []):
        problems.append("chat completions not accepted")
    if "tool-use" not in (info["capabilities"] or []):
        problems.append("no tool-use capability")
    if info["max_input_tokens"] and input_tokens > info["max_input_tokens"]:
        problems.append("input exceeds max_input_tokens")
    return info, problems

for model_id in ("deepseek-v4-pro", "deepseek-v4-flash"):
    info, problems = preflight(model_id, input_tokens=30_000)
    print(model_id, json.dumps(info, indent=2), problems)

この記事の証拠ではレスポンス内の正確なJSONレイアウトが示されていないため、lifecycleとpricingはそのまま出力しています。一度出力を確認してから、必要なフィールドを解析してください。ドキュメントではコピーした価格表をハードコードしないよう推奨しているため、起動時またはスケジュールに従ってチェックを実行してください。GET /v1/modelsのような公開ディスカバリーエンドポイントには独自のレート制限があるため、リクエストごとに呼び出すのではなく結果をキャッシュしてください。

レート制限については、2026年10月3日時点で標準のUserティアはAPIキーあたり毎分1,000リクエストを許可しています。ガイドでは、アクティブな構成は異なる場合があると述べています。429エラーが発生した場合は、コピーされた数値よりも、返されたX-RateLimit-LimitおよびRetry-Afterの値を信頼してください。

FAQ

Anthropic Messagesフォーマットを通じてdeepseek-v4-proを呼び出せますか？

はい。2026年10月3日時点で、両方のレコードがanthropic_messagesを対応フォーマットとしてリストしています。コーディングエージェントガイドでは、Anthropic MessagesのベースURLを、Chat Completionsが使用する/v1サフィックスなしのhttps://api.tokenlab.shとしています。ツールスキーマはフォーマットによって異なるため、会話全体で1つのフォーマットを維持してください。

deepseek-v4-proまたはdeepseek-v4-flashからの503エラーをリトライすべきですか？

エラーボディでretryableがtrueとされている場合のみリトライし、その場合はretry_afterを待ってください。retryable: falseの503 all_channels_failedは、選択した配信ティアにリクエストの供給がないことを意味します。繰り返しても意味はありません。エラーガイドの説明に従い、別のモデルを選択する前にGET /v1/modelsを確認してください。

deepseek-v4.1-flashはdeepseek-v4-flashを置き換えますか？

カタログにはそう記載されていません。2026年10月3日時点で、deepseek-v4-flashのレコードには代替モデルは示されておらず、deepseek-v4.1-flashはアクティブ状態でした。両者は制限と定価を共有しており、新しいモデルにはreasoningとvision機能が追加されています。タスクでテストを行い、モデルIDを指定して意図的に切り替えてください。

キャッシュされたトークンはエージェントループでdeepseek-v4-flashをより安価にしますか？

安価になる可能性があります。レコードには、通常の入力の0.15ドルに対し、100万トークンあたり0.003ドルのオフピークキャッシュ読み取り価格が記載されています。コストガイドでは、割引を当てにする前に、レスポンスまたは使用状況でキャッシュされたトークンの使用を確認するよう指示しています。キャッシュの動作と価格はモデルによって異なります。

deepseek-v4-flashへのルーティングでレート制限は上がりますか？

いいえ。レート制限ガイドでは、より高速なモデルを使用してもアカウントのリクエスト制限は上がらないとされています。モデルの速度、トークン制限、アカウントのレート制限は個別の制約であり、制限はAPIキーごとに適用されます。

ルーターを接続する前に、TokenLabモデルページで現在のdeepseek-v4-proおよびdeepseek-v4-flashのエントリを確認してください。