DeepSeek APIのWeb検索・URL読み取り・料金・400エラー対策
DeepSeek Flashのサーバー側Web検索とURL読み取りを、Chat Completions、Messages、Responsesの各APIで設定する方法を説明します。thinkingモードの選択、signatureを維持した複数ターンの会話、検索・ページ取得料金とトークン料金の計算、400エラーの対処を取り上げます。Search、Fetch、OCR、ASR、TTSの独立したAPIとの使い分けも解説します。
目次

チャットボットにWeb検索と出典の表示が必要なら、deepseek-flashでdeepseek_web_searchを宣言し、thinkingを無効にしてください。複数段階の調査にはthinkingを有効にし、ユーザーが指定したリンクを読む場合はdeepseek_read_urlを使います。まずDeepSeek公式APIで動作を確認してください。互換APIゲートウェイが独自のツール宣言や応答フィールドをそのまま扱えるとは限りません。
DeepSeekは2026年11月13日にこれらの機能を公開しました。検索、URLの読み取り、ファイル解析、音声処理には、通常のモデルトークン料金とは別に利用料金が発生します。
この記事では、3種類の会話APIでの設定、実行例、課金カウンター、400エラーへの対処、独立したツールAPIとの使い分けを説明します。
11月13日のDeepSeek API更新で何が変わったか
DeepSeekは、それまで主にチャットアプリで提供していた機能を開発者向けAPIに追加しました。
11月13日の公式更新履歴によると、モデルIDがdeepseek-flashのDeepSeek V4.1 Flashでは、次の機能を利用できます。
- 出典付きのWeb検索と画像検索。
- 推論を進めながら検索、ページの閲覧、ページ内検索を繰り返す深い検索。
- ユーザーのメッセージに含まれるURLの読み取り。
- PDF、Officeファイル、画像の入力と、テキスト抽出またはレイアウト解析。
- モデルへの入力と出力に対する安全性チェック。
これらはMessages、Responses、Chat Completionsの各APIで利用できます。検索やページ取得などのツール処理はDeepSeekのサーバーで実行され、結果はモデルのコンテキストに組み込まれます。
組み込みツールを使う場合、アプリ側で検索処理やページ取得処理を別途実装する必要はありません。
一方、Search、Fetch、OCR、ASR、TTSには独立したAPIもあります。こちらは検索結果、抽出テキスト、音声の書き起こし、生成音声をアプリのコードへ直接返します。
検索モードの選び方
deepseek_web_searchの動作はthinkingの設定で変わります。
| モード | ツールの宣言 | Thinking | 動作 |
|---|---|---|---|
| 通常のWeb検索 | deepseek_web_search | 無効 | 必要に応じて検索し、出典付きで回答します |
| 深い検索 | deepseek_web_search | 有効 | 複数の推論ステップで検索、ページ閲覧、ページ内検索を行います |
| URL読み取り | deepseek_read_url | 無効、またはWeb検索を使わずに有効 | ユーザーの最新メッセージにあるURLを確認します |
| 検索とURL読み取り | 両方 | 無効 | 検索するか、指定されたURLを読むかをモデルが選びます |
深い検索では、回答するまでにおよそ20回までのツール呼び出しが行われる場合があります。これはドキュメントに示された概数で、毎回その回数まで実行する保証ではありません。
2つのツールを併用する際には注意が必要です。
thinkingが有効でdeepseek_web_searchを宣言すると、そのターンでは深い検索が使用されます。deepseek_read_urlの独立したURL読み取り処理は実行されません。
ユーザーが指定したURLを確実に読み取り対象にしたい場合は、deepseek_read_urlだけを宣言してください。ただし、実際にどのリンクを読むかはモデルが判断します。
サーバーツールを宣言しても、呼び出しが必ず発生するわけではありません。 検索やページ取得の実行はモデルが判断します。
モデル自体の特徴については、DeepSeek V4.1 Flashのコーディング性能と料金の解説も参考にしてください。
Chat Completionsでdeepseek_web_searchを有効にする方法
POST https://api.deepseek.com/chat/completionsにリクエストを送り、モデルをdeepseek-flash、toolsに検索ツールを指定します。
事前にDeepSeekの有効なAPIキー、Bash、cURL、jqを用意してください。
次のBashの例は通常のWeb検索とコンテンツの安全性チェックを有効にします。最初のコマンドはAPIキーを画面に表示せずに読み取ります。入力待ちになったら、DeepSeekで作成したキーを貼り付けてください。
read -rs DEEPSEEK_API_KEY && export DEEPSEEK_API_KEY
curl -sS https://api.deepseek.com/chat/completions \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": [
{"type": "deepseek_web_search"}
],
"safety_check": {"level": "high"},
"messages": [
{
"role": "user",
"content": "What did DeepSeek announce on November 13, 2026? Cite the official sources."
}
]
}' | jq '{
error: .error,
answer: .choices[0].message.content,
citations: .choices[0].message.annotations,
tool_calls: .choices[0].message.server_tool_calls,
finish_reason: .choices[0].finish_reason,
usage: .usage
}'
検索を伴う正常な応答には、次の情報が含まれる場合があります。
choices[0].message.content:回答本文。choices[0].message.annotations:出典URLと本文内の引用位置。choices[0].message.server_tool_calls:サーバーで実行された検索ステップ。usage.server_tool_use:検索とページ取得の利用カウンター。
回答が完了するとchoices[0].finish_reason = "stop"になります。lengthは出力制限による途中終了、content_filterはコンテンツ審査による拒否を表します。
server_tool_callsが返らなくても、必ずしもエラーではありません。モデルが検索不要と判断した可能性があります。最新情報が必要な質問で再確認してください。
深い検索を有効にする
deepseek_web_searchの宣言を維持したまま、thinkingの設定を変更します。
{
"thinking": {"type": "enabled"},
"tools": [
{"type": "deepseek_web_search"}
]
}
複数の検索や情報源の比較が必要な質問に向いています。
深い検索ではページを開き、ページ内のテキストも調べられます。通常検索より推論トークンや課金対象のページ取得が増える場合があります。
実行するステップはモデルが決めます。
Web検索せずにURLを読み取る
ツールの宣言をdeepseek_read_urlだけに変更し、ユーザーの最新メッセージにURLを含めます。
{
"thinking": {"type": "disabled"},
"tools": [
{"type": "deepseek_read_url"}
],
"messages": [
{
"role": "user",
"content": "Summarize https://api-docs.deepseek.com/updates/ and identify the November 13 changes."
}
]
}
エンドポイント、モデル、認証、安全性チェックは最初のChat Completionsの例と同じものを使ってください。
URL読み取りには次の条件があります。
- URLを検出するのは最新のユーザーメッセージだけです。
- 同じURLが複数回あっても1件と数えます。
- 対象になるのは最初の10件の異なるURLまでです。
- 実際に読むURLはモデルが選びます。
- 長いページを複数読むと、各ページの内容が途中で切り詰められる場合があります。
詳しくは公式Web Toolsガイドを参照してください。
過去のメッセージにしかURLがない場合、次のリクエストで自動的に再取得されるとは限りません。
MessagesとResponsesではどう宣言するか
3つのAPIは同じサーバーツールをサポートしますが、リクエスト形式と応答構造が異なります。
| API | エンドポイント | ドキュメントのツール宣言 | Thinkingの制御 |
|---|---|---|---|
| Chat Completions | /chat/completions | {"type":"deepseek_web_search"} | thinking.type |
| Messages | /anthropic/v1/messages | {"type":"deepseek_web_search","name":"deepseek_web_search"} | thinking.type |
| Responses | /responses | {"type":"deepseek_web_search"} | reasoning.effort |
いずれもホストはhttps://api.deepseek.comです。
公式ドキュメントのMessagesの例では、ツール宣言にtypeとnameの両方が含まれます。ただし、この例だけではすべての有効なリクエストでnameが必須とは断定できません。
Messagesは認証にx-api-keyヘッダーを使います。Chat CompletionsとResponsesはAuthorization: Bearerを使います。
API形式を切り替える場合は、Messages、Chat Completions、Responsesの互換性ガイドも確認してください。モデルIDが同じでも、ツールや会話履歴の形式まで同じとは限りません。
Messages APIの例
次のBashリクエストは、Anthropic互換のMessages形式で指定URLを読み取ります。
curl -sS https://api.deepseek.com/anthropic/v1/messages \
-H "x-api-key: ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": [
{
"type": "deepseek_read_url",
"name": "deepseek_read_url"
}
],
"safety_check": {"level": "high"},
"messages": [
{
"role": "user",
"content": "Summarize https://api-docs.deepseek.com/updates/"
}
]
}' | jq '{
content: .content,
stop_reason: .stop_reason,
usage: .usage
}'
回答はcontentブロックに入ります。サーバーツールの呼び出しはserver_tool_useブロックとして返り、その後に結果のブロックが続きます。
出典はテキストブロックに付けられます。回答完了時の値はstop_reason = "end_turn"です。
ストリーミングでは、総使用量を最後のmessage_deltaイベントから取得してください。message_startのusageには最初の推論ステップ分しか含まれません。
Responses APIの例
Responses APIではthinking.typeではなくreasoning.effortを使います。
noneでthinkingを無効にし、low、high、maxで指定したレベルのthinkingを有効にします。
curl -sS https://api.deepseek.com/responses \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"reasoning": {"effort": "high"},
"tools": [
{"type": "deepseek_web_search"}
],
"safety_check": {"level": "high"},
"input": "Research the November 13, 2026 DeepSeek API update and compare the official documentation."
}' | jq '{
status: .status,
output: .output,
usage: .usage
}'
Responses APIのツール処理は、output内のweb_search_callとして返ります。最終回答はmessageアイテムで、引用元はoutput_textのannotationsに含まれます。
正常終了ならstatus = "completed"です。出力制限やコンテンツ審査で中断した場合はincomplete、生成の失敗ではfailedになることがあります。
再試行する前にincomplete_details.reasonまたはerror.codeを確認してください。
3つのAPIの応答を同一構造として解析しないでください。特にツールの実行履歴を保持する処理では注意が必要です。
複数ターンの会話でsignatureを保持する理由
deepseek_read_urlによる読み取りが成功すると、ページ内容は暗号化されたsignatureとして返ります。
ページ本文は通常のテキストとして結果ブロックに含まれません。url、title、data、published_atは主に表示用のフィールドです。
次のターンでは、DeepSeekがsignatureを使って以前のページ内容をコンテキストに復元できます。
以前のassistant応答は、kind、signature、サーバーツールの呼び出し構造を含めて変更せずに送り返してください。
次のPython例ではChat Completionsを使い、最初のassistantメッセージをそのまま次のターンへ渡します。
実行前にrequestsをインストールし、DEEPSEEK_API_KEYを環境変数としてexportしてください。
import os
import requests
endpoint = "https://api.deepseek.com/chat/completions"
headers = {
"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}",
"Content-Type": "application/json",
}
tools = [{"type": "deepseek_read_url"}]
messages = [
{
"role": "user",
"content": (
"Read https://api-docs.deepseek.com/updates/ "
"and summarize the November 13, 2026 entry."
),
}
]
def complete_turn(history):
response = requests.post(
endpoint,
headers=headers,
json={
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": tools,
"safety_check": {"level": "high"},
"messages": history,
},
timeout=180,
)
response.raise_for_status()
data = response.json()
if data.get("error"):
raise RuntimeError(data["error"])
choice = data["choices"][0]
if choice["finish_reason"] != "stop":
raise RuntimeError(
f"Incomplete response: {choice['finish_reason']}"
)
return choice["message"]
first_reply = complete_turn(messages)
# Preserve the complete assistant object, including server_tool_calls.
messages.append(first_reply)
messages.append(
{
"role": "user",
"content": "Which developer features does that entry list?",
}
)
second_reply = complete_turn(messages)
print(second_reply["content"])
これはドキュメントに基づく会話形式の例です。実際のAPIでテストした結果を示すものではありません。
first_reply["server_tool_calls"]を確認し、モデルが実際にURLを読んだか調べてください。read_linkがなければ、最初の応答には保持するべきページのsignatureがありません。
各APIで保持するデータは次のとおりです。
| API | 次のターンに送り返す内容 |
|---|---|
| Messages | kindとsignatureを含む以前のassistantのcontentブロック |
| Responses | web_search_call、kind、signatureを含む以前のoutputアイテム |
| Chat Completions | server_tool_callsを含むassistantメッセージ全体 |
ライブラリやゲートウェイがsignatureを削除しても、次のリクエスト自体は成功する場合があります。しかし、以前に読んだページの内容は復元されません。
前のターンの検索結果、深い検索で開いたページ、途中の推論過程は、全文が自動的に次のターンへ引き継がれるわけではありません。通常は回答文のみが引き継がれます。有効なsignatureを持つURL読み取りは、その例外としてドキュメントに記載されています。
ページ内容を次のターンでも参照したい場合、assistantの履歴をroleとcontentだけに単純化しないでください。
独立したSearch、Fetch、OCR、ASR、TTSを使う場面
検索やデータ処理の各ステップをアプリ側で制御したいなら、独立したAPIを使ってください。
組み込みツールと異なり、これらのAPIは結果をコードへ直接返します。取得内容の検証、フィルタリング、保存、モデルへの入力をアプリ側で管理できます。
独立したAPIのエンドポイントと入力
| API | https://api.deepseek.com上のエンドポイント | 必須の入力 | 結果 |
|---|---|---|---|
| Search | POST /v1/tools/search | JSONのquery | 構造化されたresults |
| Fetch | POST /v1/tools/fetch | JSONのurl | ページのtitleとMarkdown形式のcontent |
| OCR | POST /v1/tools/ocr | multipartのfile、purpose | pages[].textとpage_count |
| ASR | POST /v1/tools/asr | multipartの音声file | 書き起こしのtextとduration_ms |
| TTS | POST /v1/tools/tts | JSONのtext | WAVまたはPCM音声 |
5つともBearer認証を使います。
以下は各APIを呼び出すBashの例です。先ほど設定したDEEPSEEK_API_KEYを使用します。
# Search for pages and return structured results.
curl -sS https://api.deepseek.com/v1/tools/search \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"query":"DeepSeek API release","count":5,"need_content":true}' \
| jq '.results[] | {title, url, summary, content}'
# Fetch one page as Markdown.
curl -sS https://api.deepseek.com/v1/tools/fetch \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"url":"https://api-docs.deepseek.com/updates/"}' \
| jq '{title, content}'
# Extract text from a local PDF.
curl -sS https://api.deepseek.com/v1/tools/ocr \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F purpose="text_recognition" \
-F file="@document.pdf" \
| jq '{page_count, pages}'
# Transcribe a local audio file.
curl -sS https://api.deepseek.com/v1/tools/asr \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F file="@speech.wav" \
| jq '{text, duration_ms}'
# Generate a WAV file.
curl -sS https://api.deepseek.com/v1/tools/tts \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"text":"Hello from DeepSeek.","voice_id":"stella"}' \
--output speech.wav
OCRとASRの例ではローカルの入力ファイルが必要です。TTSのコマンドは作業ディレクトリにspeech.wavを保存します。
2026年11月14日時点の主な制限は次のとおりです。
- Search:
queryは1–128文字のUnicode文字列です。countで1–50件の結果を指定できます。アカウントごとの上限は100 QPSです。 - Fetch: 1リクエストにつきHTTPまたはHTTPSのURLを1件指定します。対象サイトのアクセス制限が適用されます。アカウント上限は25 QPSで、ドメイン別のQPS制限もあります。
- OCR: ファイルの最大サイズは100 MiB、最大1,000ページです。アカウントごとに同時実行できる認識処理は15件までです。
- ASR: 1リクエストにつき音声は最大120秒、サイズは最大8 MiBです。16-bit PCM WAVとOgg Opusをサポートします。
- TTS: 1リクエストあたり最大10,000課金対象文字です。全文の音声生成とWebSocketによるストリーミングを利用できます。
独立したSearchではsite:、lang:、after:などの検索演算子が使えます。2026年11月14日時点で、独立したSearch APIは画像検索に対応していません。画像検索は組み込みWebツールで利用できます。
詳しい入力条件はSearchとFetch、OCR、ASR、TTSのドキュメントを確認してください。
ファイル入力と独立したOCRの違い
文書の内容についてモデルに質問したい場合はファイル入力を使います。抽出されたテキストをアプリのコードで直接使いたい場合は、独立したOCRを選びます。
ファイル入力の手順は次のとおりです。
multipart/form-dataを使い、POST https://api.deepseek.com/filesへ文書をアップロードします。- フォームの
purposeを**fileより先に**送信してください。順番を逆にすると400が返る場合があります。 purposeにtext_recognitionまたはrich_layout_recognitionを指定します。- 解析が成功したら
file_idを取得し、後続のdeepseek-flashへの会話リクエストで参照します。
次のBashの例では、ローカルのPDFをアップロードします。
curl -sS https://api.deepseek.com/files \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F purpose="text_recognition" \
-F file="@report.pdf" \
| jq '{id, filename, purpose}'
-Fオプションによってmultipart形式のフォームリクエストが作成されます。purpose、fileの順序を守ってください。multipartのContent-Typeの境界文字列を手動で設定する必要はありません。cURLが生成します。
アップロードの応答に含まれるidを、会話リクエストではfile_idとして使います。解析はアップロード中に行われるため、別途状態を確認する処理は不要です。
text_recognitionはテキストのみを抽出し、図表や写真をモデルの解釈に利用しません。rich_layout_recognitionでは検出した図版も文書内の対応する位置でモデルへ渡します。
Chat Completionsのユーザーメッセージでファイルを参照する形式は次のとおりです。
{
"role": "user",
"content": [
{"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
{"type": "text", "text": "Summarize the key points of this document."}
]
}
サンプルの識別子は、アップロードで返された実際のfile_idに置き換えてください。
1リクエストで参照できる文書は最大20件です。抽出されたテキストの合計は8 MiBまでです。
解析の料金はアップロード成功時に1回だけ発生します。その文書を参照する後続の会話では、文書内容に対する入力トークン料金がかかります。
実装前にファイル解析ガイドも確認してください。
DeepSeekのWebツールと各APIの料金はいくらか
2026年11月14日時点で、DeepSeekはモデルの推論料金とツールの利用料金を別々に請求します。
公式料金表に掲載された米ドル建ての料金は次のとおりです。
| 機能 | 課金単位 | 料金 |
|---|---|---|
| テキストWeb検索 | 1,000回の課金対象検索 | $0.75 |
| 画像検索 | 1,000回の課金対象検索 | $0.75 |
| Web FetchまたはURL読み取り | 1,000回の課金対象取得 | $0.75 |
| ファイル解析またはOCR | 1,000ページの正常処理 | $0.225 |
| ASR | 1時間の音声 | 期間限定$0.058、通常$0.116 |
| TTS | 10,000課金対象文字 | 期間限定$0.225、通常$0.45 |
ASRとTTSの割引は期間限定とされています。確認した料金表とAPIガイドには終了日が記載されていません。
TTSでは中国語の漢字1文字は2文字として課金されます。空白を含むその他の文字は1文字として数えられます。
ASRは音声の長さを秒単位で計算し、端数を切り上げます。
実際の課金回数を表すusageフィールド
組み込みWebツールでは、次のカウンターを使用してください。
usage.server_tool_use.tool_search:課金対象のテキスト検索回数。usage.server_tool_use.tool_image_search:課金対象の画像検索回数。usage.server_tool_use.tool_fetch:課金対象のページ取得回数。
web_search_requestsやweb_fetch_requestsから料金を直接計算しないでください。
これらはエラーを含む結果ブロックの件数を表す表示用カウンターで、課金回数とは異なります。
1回のWeb検索ツール呼び出しで複数のクエリを実行する場合があります。成功したクエリが3件なら、tool_searchが3増えることがあります。
検索が失敗した場合や結果がなかった場合は課金されません。
画像検索では画像1件が検索1回として数えられます。モデルが画像内で選択した領域も、1領域につき追加の検索1回として数えられます。 失敗した検索や結果のない検索は課金されません。
URL読み取りはページの取得に成功した場合に課金されます。取得後の安全性チェックで結果がエラーに置き換わっても、取得料金が発生することがあります。
深い検索では、すでにコンテキストにあるページを再度開いても新たなFetch料金はかかりません。ページ内テキストの検索も無料です。
独立したSearchとFetchでは、成功したAPIリクエスト1回ごとに課金されます。独立したSearchの結果件数が多くても、リクエスト料金は増えません。
100リクエスト分の料金計算例
thinkingを無効にしたDeepSeek Flashへの100リクエストで、次の利用量が発生したと仮定します。
| 項目 | 仮定した使用量 |
|---|---|
| 課金対象のテキスト検索 | 200 |
| 課金対象のページ取得 | 100 |
| キャッシュにヒットしなかった入力トークン | 200,000 |
| キャッシュから読み取った入力トークン | 0 |
| 安全性チェックを含む出力トークン | 50,000 |
| 画像検索 | 0 |
deepseek-flashのオフピーク料金は、キャッシュミスの入力トークン100万あたり$0.15、出力トークン100万あたり$0.60です。
計算は次のようになります。
Text searches = 200 / 1,000 × $0.75 = $0.150
Page fetches = 100 / 1,000 × $0.75 = $0.075
Input tokens = 200,000 / 1,000,000 × $0.15 = $0.030
Output tokens = 50,000 / 1,000,000 × $0.60 = $0.030
Estimated total = $0.285 for 100 requests
この条件での推定合計は100リクエストで$0.285です。実測値や実際の請求額ではなく、仮定した利用量に基づく試算です。
DeepSeekの公開スケジュールでは、ピーク時間は月曜日から金曜日の01:00–04:00および06:00–10:00 UTCです。中国の祝日はピーク料金の対象外です。
ピーク時間のFlash料金は、キャッシュミス入力トークン100万あたり$0.30、出力トークン100万あたり$1.20になります。
同じ使用量なら、ピーク時間の推定合計は$0.345です。
実際の料金は推論ステップ、thinkingトークン、キャッシュヒット、画像検索、ページ取得、安全性チェック、適用料金によって変わります。
thinkingトークンはoutput_tokensに含まれます。別料金として二重に加算しないでください。
エラーになったリクエストも課金されるか
処理がどこまで進んだかによっては課金されます。
生成開始後に推論やツール処理が失敗した場合、HTTPステータスが200でも応答本文にエラーが含まれることがあります。
失敗前に実行済みの推論、検索、ページ取得には通常どおり料金がかかります。
ストリーミングでは、最初のHTTPステータスだけで成功と判断せず、最終イベントと最終usageを確認してください。
非ストリーミングのChat Completionsでも、HTTP 200の場合にerrorの有無を調べてください。
Responsesではfailedやincompleteを含むstatusを確認します。
Webツールで発生する400エラーの直し方
多くの検証エラーは、サーバーツールを通常の関数ツールと同じように強制実行しようとしたり、非対応のオプションを組み合わせたりすることで発生します。
Web Toolsのエラーリファレンスには、次のメッセージが記載されています。
| エラーメッセージ | 原因 | 対処 |
|---|---|---|
tool_choice: deepseek_web_search cannot be forced | tool_choiceでWebツールを強制指定した | 強制指定を削除してモデルに選択させます |
tools: deepseek_web_search can only be declared once | 同じツールを重複宣言した | 宣言を1件にします |
tools: allowed_domains is not supported by deepseek_web_search | 未対応のドメイン・位置指定がある | allowed_domains、blocked_domains、user_locationを削除します |
tools: other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yet | 競合するサーバーツールを宣言した | 競合するサーバーツールを取り除きます |
safety_check: level must be low or high | 安全性チェックのレベルが無効 | lowかhighを指定します |
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous request | Webツールを使った途中の回答を継続しようとした | 継続ではなく元のリクエストを再送します |
元のエラーメッセージではフィールド名がバッククォートで囲まれています。この表では読みやすいように省略しています。
すべての修正を順番に試す必要はありません。自分のエラーに対応する原因を直し、再送して結果を確認してください。
tool_choiceでWeb検索を強制できるか
できません。tool_choiceでdeepseek_web_searchまたはdeepseek_read_urlを強制指定すると、400になります。
tool_choiceをnoneにすると、URL読み取りを含むすべてのツールが無効になります。
Chat CompletionsとResponsesでは、Webツール使用時のtool_choice: "required"はautoとして扱われます。これも検索の実行を保証しません。
アプリで指定したクエリを必ず実行する必要がある場合は、独立したSearch APIを使ってください。
通常のfunction callsと併用できるか
ドキュメントのエラーは、競合するサーバーツール宣言に関するものです。
その記述から、すべての通常の関数ツールが禁止されているとは断定できません。一方、すべてのエージェント環境で問題なく併用できることも検証されていません。
Responsesでは、これらのツールとweb_searchを同時に宣言できません。custom、namespace、tool_searchなどのツール形式も対応していません。
Claude Code、OpenCode、既存の関数を使う自作エージェントへ追加する前に、実際のリクエストとツールの往復処理を確認してください。
WebツールなしでOpenAI互換リクエストが成功しても、新しい組み合わせの動作確認にはなりません。
Webツールを使った回答の継続が400になる理由
次の会話ターンを送ることと、途中で停止した同じ回答の続きを生成することは別の処理です。
通常の次のターンでは、完了したassistant応答の後ろに新しいユーザーメッセージを追加します。
継続生成では、途中のassistant応答をそのまま書き足そうとします。
DeepSeekでは、deepseek_web_searchまたはdeepseek_read_urlを使った回答の継続生成はできません。
検索を伴う回答が途中で切れた場合、適切な出力上限で元のリクエストを送り直してください。検索やページ取得が再実行され、追加料金が発生する可能性があります。
Webツールを使わない継続生成では、Chat Completionsのbetaエンドポイントで最後のassistantメッセージにprefix: trueを指定する方法があります。ただし、Webツール使用時の制限を回避するものではありません。
url_not_accessible、url_not_allowed、unavailableの意味
ページ取得に失敗すると、signatureのないweb_fetch_tool_result_errorが返ります。
原因はerror_codeで区別します。
| エラーコード | 意味 | 対処 |
|---|---|---|
url_not_accessible | リンク先を読み取れなかった | URL、ページの公開状態、認証、サイトの制限を確認します |
url_not_allowed | 読み取りが許可されていない、または安全性チェックで拒否された | 制限を回避せず、許可された別の情報源を使います |
unavailable | サービス停止、深い検索でのページ閲覧失敗、または処理の未完了 | 応答状態を調べ、必要に応じて回数を制限して再試行します |
これらは同じエラーではありません。
url_not_allowedはネットワーク障害とは限りません。コンテンツの安全性チェックによる拒否の場合もあります。
unavailableだからといって必ず無料とは限りません。エラーになる前にページ取得が完了している可能性があります。
ストリーミングでは、ツール呼び出しと結果を識別子で対応付けてください。複数ページを扱う場合、呼び出しの直後に対応する結果が届くとは限りません。
終了状態も確認してください。
- Messagesの
end_turnは回答完了です。 max_tokensは出力上限または利用可能なコンテキストの不足です。refusalはコンテンツ審査による拒否です。
Chat Completionsで対応する終了理由にはstop、length、content_filterがあります。
一般公開するアプリでは、安全性チェックを有効にしてください。
{
"safety_check": {"level": "high"}
}
DeepSeekは一般向けサービスに安全性チェックを有効にするよう求めています。この機能は入力と出力を基本的に審査しますが、アプリ側のモデレーションや、適用法令上の登録・AI生成コンテンツの表示義務を代わりに満たすものではありません。
拒否された回答でも、それまでに消費したトークンが課金される場合があります。
各APIでの拒否の形式はModel Content Safetyガイドを確認してください。
組み込みWebツールと独自の検索APIの選び方
モデル自身に会話中の調査を任せたいなら組み込みツールを選びます。検索内容や取得結果をアプリ側で制御する必要があるなら、独立したAPIを使ってください。
| アプリの目的 | 最初に選ぶもの | 理由 |
|---|---|---|
| 出典付きの回答を返すチャットボット | thinking無効のdeepseek_web_search | 検索処理を自作する必要が少なくなります |
| 複数の情報源を調べる | thinking有効のdeepseek_web_search | 検索とページ確認を複数回実行できます |
| ユーザー指定のリンクを要約する | deepseek_read_url | 対象URLを読み、signatureでページ内容を保持できます |
| 指定サイトの検索や構造化結果が必要 | 独立したSearch | クエリや検索結果をコードで制御できます |
| 指定URLからMarkdownを取得する | 独立したFetch | ページ本文を直接受け取れます |
| 多数の文書から文字を抽出する | 独立したOCR | ページごとの抽出結果が得られます |
| アップロードした文書に質問する | File Parsingとdeepseek-flash | 文書がモデルのコンテキストに入ります |
| 音声入力や読み上げを実装する | ASRとTTS | 音声処理専用のAPIを使用できます |
既存のコーディングエージェントでは、外部検索連携を維持する方が適することもあります。既存のツール宣言や検索処理を変更せずに済むためです。
Parallel Search MCPを既存エージェントに追加するガイドでは別の方法を紹介しています。同じタスクで実際の料金、ツールの互換性、取得内容を比較して判断してください。
BetterTokenなどの互換ゲートウェイでは使えるか
2026年11月14日時点で、BetterTokenのモデル一覧にはdeepseek-flashが掲載されていました。利用経路を選ぶ前に現在のモデル料金を確認してください。
ただし、モデルが掲載されていることだけでは、DeepSeekの新しいサーバーツールを利用できるとは確認できません。
BetterToken経由でのツール宣言の転送、signatureの保持、usage.server_tool_useの返却、追加ツール料金の計上は未検証です。
そのため、この記事のコード例はDeepSeek公式エンドポイントを使用しています。
互換ゲートウェイを使う前に、検索1回、URL読み取り1回、signatureを保持する次の会話ターンを試してください。さらにusageと実際の請求額を照合します。
新規アプリなら、まずthinkingを無効にした通常検索から始めてください。出典と課金カウンターを確認し、複数段階の調査が必要な場合だけ深い検索を有効にします。処理をコードで管理する必要がある部分には、独立したSearchとFetchを使ってください。