DeepSeek V4 API の使い方

DeepSeek V4は、発売初日からAPIが利用可能になりました。モデルIDはdeepseek-v4-proとdeepseek-v4-flashで、エンドポイントはOpenAI互換、ベースURLはhttps://api.deepseek.comです。つまり、GPT-5.5やその他のOpenAI形式のAPIで既に使用しているクライアントは、ベースURLを一度変更するだけでV4にも対応します。

このガイドでは、認証、重要なすべてのパラメータ、PythonおよびNodeの例、思考モードの計算、ツール呼び出し、ストリーミング、そして反復作業中にコストを可視化するApidogベースのワークフローについて説明します。

製品概要については、DeepSeek V4とはをご覧ください。無料でDeepSeek V4を使用する方法については、DeepSeek V4を無料で利用する方法をご覧ください。

要約

• DeepSeek V4は、`https://api.deepseek.com/v1/chat/completions`の**OpenAI互換**エンドポイントと、`https://api.deepseek.com/anthropic`の**Anthropic互換**エンドポイントで利用可能です。
• モデルID: `deepseek-v4-pro` (合計1.6T、アクティブ49B) および `deepseek-v4-flash` (合計284B、アクティブ13B)。
• 両バリアントは**1Mトークンのコンテキスト**と3つの推論モードをサポートしています: `non-thinking`、`thinking`、`thinking_max`。
• DeepSeekが推奨するように`temperature=1.0, top_p=1.0`を使用してください。GPT-5.5やClaudeのデフォルト設定をインポートしないでください。
• レガシーIDの`deepseek-chat`と`deepseek-reasoner`は**2026年7月24日**に非推奨になります。それまでに移行してください。
• リクエストの再実行、思考モードの比較、シェル履歴からキーを保護するためにApidogをダウンロードしてください。

前提条件

最初のリクエストの前に、4つの準備をしてください。

• platform.deepseek.comで、少なくとも2ドルをチャージしたDeepSeek開発者アカウント。残高がない場合、呼び出しは`402 Insufficient Balance`を返します。
• 請求対象となるプロジェクトにスコープされたAPIキー。プロジェクトスコープのキーは、本番環境ではアカウントキーよりも安全です。
• OpenAI互換のベースURLにアクセスできるSDK。Python `openai>=1.30.0`およびNode `openai@4.x`はどちらも変更なしで動作します。
• ターミナルを埋めることなくリクエストを再実行できるAPIクライアント。curlは1回の呼び出しには機能しますが、その後はApidogを使用してください。

キーを一度エクスポートします。

export DEEPSEEK_API_KEY="sk-..."

エンドポイントと認証

2つのベースURLが2つのリクエスト形式に対応します。

POST https://api.deepseek.com/v1/chat/completions    # OpenAI format
POST https://api.deepseek.com/anthropic/v1/messages  # Anthropic format

既存のAnthropic形式のコードベースがない限り、OpenAI互換を選択してください。このガイドの残りの部分では、OpenAI形式を使用します。

認証は、標準の`Authorization`ヘッダーにベアラー・トークンを使用します。最小限の有効なリクエストは次のとおりです。

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [
      {"role": "user", "content": "Explain MoE routing in two sentences."}
    ]
  }'

成功したレスポンスは、`choices`配列、入力および出力トークンに分割された`usage`ブロック（思考モードがオンの場合は`reasoning_tokens`も含まれる）、およびトレースに使用できる`id`を含むJSONボディを返します。失敗した場合は、`error.code`と`error.message`を含む標準のOpenAIエンベロープを返します。

リクエストパラメータ

すべてのフィールドはコストまたは動作にマッピングされます。`deepseek-v4-pro`および`deepseek-v4-flash`のマッピングは以下のとおりです。

`thinking_mode`はコストに最も影響する要素です。`non-thinking`は推論トレースを完全にスキップし、およそV3.2の速度でトークンを返します。`thinking`は追加のトークンを消費しますが、コードと数学の精度を向上させる推論ブロックを有効にします。`thinking_max`はDeepSeekのヘッドラインテーブルにあるスコアを生成します。これも最も多くのトークンを消費し、384K以上のコンテキスト予算を必要とする唯一のモードです。

Pythonクライアント

公式の`openai` SDKは、ベースURLのオーバーライドで使用できます。LangChain、LlamaIndex、DSPyなど、既存のOpenAI互換ラッパーはすべて動作します。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/v1",
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    extra_body={"thinking_mode": "thinking"},
    temperature=1.0,
    top_p=1.0,
    max_tokens=2048,
)

choice = response.choices[0]
print("Content:", choice.message.content)
print("Reasoning tokens:", response.usage.reasoning_tokens)
print("Total tokens:", response.usage.total_tokens)

`extra_body`トリックは、ライブラリをパッチすることなく、OpenAI SDKを介してDeepSeek固有のパラメータを渡す方法です。

Nodeクライアント

Nodeでも同じ構造です。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: "https://api.deepseek.com/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-v4-flash",
  messages: [
    { role: "user", content: "Explain the Muon optimizer in plain English." },
  ],
  thinking_mode: "thinking",
  temperature: 1.0,
  top_p: 1.0,
});

console.log(response.choices[0].message.content);
console.log("Usage:", response.usage);

Node SDKは不明なフィールドをサイレントに受け入れるため、`thinking_mode`は`extra_body`なしでトップレベルで渡されます。

ストリーミング応答

`stream: true`を設定し、SSEチャンクを反復処理します。形式はOpenAIと完全に一致します。

stream = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Stream a 300-word essay on MoE."}],
    stream=True,
    extra_body={"thinking_mode": "non-thinking"},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)

思考モードがオンの場合、推論トレースは個別にストリーミングされます。`delta.reasoning_content`フィールドがそれらを運び、UIに表示したり、破棄したりできます。

ツール呼び出し

V4は標準のOpenAIツール呼び出しスキーマをサポートしています。`tools`配列で定義された関数は呼び出し可能になり、モデルがいつ呼び出すかを決定します。

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Return the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Weather in Lagos in Celsius?"}],
    tools=tools,
    tool_choice="auto",
    extra_body={"thinking_mode": "thinking"},
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

そこから、関数を呼び出し、結果を`role: "tool"`メッセージとして追加し、ループを続行するために再度APIを呼び出します。このパターンは、OpenAIおよびAnthropicのツール使用ループと同一です。

JSONモード

構造化された出力には、明示的にJSONを要求し、応答形式を設定します。

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "Reply with a single JSON object."},
        {"role": "user", "content": "Summarize this release note as {title, date, bullets}: ..."},
    ],
    response_format={"type": "json_object"},
    extra_body={"thinking_mode": "non-thinking"},
)

JSONモードは有効なJSONを強制しますが、特定のスキーマを強制するわけではありません。スキーマ検証には、クライアント側でPydanticまたはZodと組み合わせて使用してください。

Apidogでコレクションを構築する

ターミナルからリクエストを再実行するとクレジットを消費し、実行間の差分が隠れてしまいます。実際の使用に耐えうるワークフローは次のとおりです。

1. Apidogをダウンロードしてプロジェクトを作成します。
2. `{{DEEPSEEK_API_KEY}}`を秘密変数として保存した環境を追加します。
3. `Authorization: Bearer {{DEEPSEEK_API_KEY}}`ヘッダーを持つ`{{BASE_URL}}/chat/completions`へのPOSTリクエストを保存します。
4. `model`と`thinking_mode`をパラメータ化して、リクエストを重複させることなくバリアント間でA/Bテストができるようにします。
5. 各実行で応答ビューアを使用して`usage.reasoning_tokens`を検査します。これは、不要な思考モードに料金を支払っているかどうかを示す最も明確な指標です。

Apidogで一致するGPT-5.5 APIコレクションを既に実行しているチームは、それを複製し、ベースURLを`https://api.deepseek.com/v1`に交換し、モデルIDを交換するだけで、数分で両プロバイダー間で比較プロンプトを実行できます。

エラー処理

エンベロープはOpenAIと完全に一致します。最初に遭遇するであろうものは次のとおりです。

呼び出しを、指数バックオフで429および5xxを処理するリトライヘルパーで囲んでください。4xxエラーは論理バグであり一時的な障害ではないため、自動的に再試行しないでください。

コスト管理パターン

4つのパターンで支出を予測可能に保ちます。

1. デフォルトはV4-Flashにする。 品質向上効果が測定されたプロンプトに対してのみV4-Proに切り替えてください。
2. `thinking_max`をフラグの背後にゲートする。 これは非常に高価なモードであるため、正確性がレイテンシよりも優先される場合にのみ利用してください。
3. `max_tokens`を上限設定する。 ほとんどの回答は2,000出力トークンに収まります。1Mコンテキストは入力用であり、出力用ではありません。
4. すべての呼び出しで`usage`をログに記録する。 入力、出力、推論の数をオブザーバビリティスタックに送信します。突然の推論トークンの急増に関するアラートは、逸脱したプロンプトを捕捉します。

古いDeepSeekモデルからの移行

古い`deepseek-chat`および`deepseek-reasoner`のIDは、2026年7月24日に非推奨になります。移行は呼び出しサイトごとに1行の差分で済み、リクエストおよびレスポンスの形式は変更されません。

-  model="deepseek-chat"
+  model="deepseek-v4-pro"

本番環境に移行する前に、Apidogで並行してA/B比較を実行してください。応答品質の向上は通常、切り替えの価値がありますが、いずれにしても非推奨の期限がそれを強制します。

よくある質問

DeepSeek V4 APIは本番環境に対応していますか？ はい。APIは2026年4月23日にウェイトと共に公開されました。DeepSeek V3およびV3.2は1年以上にわたり同じインフラストラクチャで大規模に稼働していたため、APIのインターフェースは成熟しています。

V4はAnthropicメッセージ形式をサポートしていますか？ はい。`https://api.deepseek.com/anthropic/v1/messages`を指定し、Anthropic形式のペイロードを送信してください。両方の形式が同じ基盤モデルにアクセスします。

コンテキストウィンドウはどれくらいですか？ V4-ProとV4-Flashの両方で100万トークンです。なお、Think Maxモードでは最低384Kの作業ウィンドウが推奨されます。

送信前に入力トークンをどのようにカウントしますか？ 推定には標準のOpenAIトークナイザーを使用してください。DeepSeekは、すべての応答の`usage`ブロックで正確な数を公開しています。本番環境の予算編成には、応答側のカウントを信頼してください。

API経由でファインチューニングできますか？ リリース時点ではできません。ファインチューニングは現在、Hugging Faceで自己ホストされたBaseチェックポイントを介して行われます。

APIは無料で試用できますか？ アカウントレベルでの無料枠はありませんが、新規登録者には試用クレジットが提供される場合があります。