DeepSeek APIのWeb検索とファイルアップロード設定ガイド

DeepSeekは2026年11月13日、アプリで使っていた機能をAPIのパラメーターから利用できるようにした。組み込みの検索はモデルが実行を判断し、検索結果が返ったクエリ単位で課金される。一方、単体のSearch／Fetch APIはコード側で実行を制御し、成功したリクエストごとに課金される。ファイルアップロードは別のFiles APIを使い、file_idで参照する仕組みだ。

思考モードを有効にしたリクエストでは、最大でおよそ20回のツール呼び出しに分岐することがある。検索とページ取得の回数分だけ課金されるため、実際のコストはタスクによって変わる。本稿では、有効化の方法、ファイルアップロード、タスク単位の料金計算、用途に応じた選び方を整理する。

11月13日のアップデートでDeepSeek App APIに追加された機能

DeepSeekの発表The full DeepSeek App experience, now via APIにより、deepseek-flash（DeepSeek-V4.1-Flash）でWeb検索、ファイル入力、URLの読み込みをAPIから利用できるようになった。

Build a Chatbot guideによると、同じ機能にはMessages API、Responses API、Chat Completions APIの3つのインターフェースからアクセスできる。ツール呼び出しとコンテキストの組み立てはサーバー側で処理されるため、クライアントは構造化されたブロックを表示し、そのまま返せばよい。配線の流れはオープンソースのブラウザーデモで確認できるが、あくまでデモ用途と位置付けられている。

Web検索とURL読み込みを有効にする

Web Tools guideにあるとおり、deepseek-flashのリクエストにあるtools配列へ、次の2つのツールを指定する。

"tools": [{"type": "deepseek_web_search"}, {"type": "deepseek_read_url"}]

思考モードを無効にすると、deepseek_web_searchはチャット検索に近い動作になる。検索するかどうかはモデルが判断し、1回の呼び出しで複数のクエリを送信でき、回答には引用も付く。思考モードを有効にすると、検索に加えてopen_pageやfind_in_pageも推論の途中で組み合わされ、回答までに最大でおよそ20回のツール呼び出しが行われる。

同じWeb Tools guideには、次の制限も記載されている。

• 対象になるのは最新のユーザーメッセージに含まれるURLだけで、異なるURLは先頭から10件まで。どのURLを読むかはモデルが決める。
• tool_choiceでツールを強制することはできない。ツール名を指定するとHTTP 400になり、"none"を指定するとURL読み込みも無効になる。
• Webツール、高い安全性設定、タイトル生成のいずれかを有効にすると、temperature、top_pなど複数のツール制御フィールドは指定しても黙って無視される。
• Webツールを使った回答はそのまま継続できないため、リクエストを再送する必要がある。

「1,000リクエストあたり0.75ドルなら、エージェントが裏側で何回呼び出すのか知りたい。一般的な調査タスクの料金を計算した人はいない？」— r/DeepSeekのu/Glum-Guitar-5083

課金方式は利用経路によって異なる。組み込みのWeb検索は、結果が返ったクエリ単位で課金されるため、1回の呼び出しに3つのクエリを含めれば3件として数えられる。組み込みのFetchは取得したページごとに課金され、安全性の確認後にurl_not_allowedやunavailableへ置き換えられたページも対象になる。ただし、取得できなかったリンクは課金されない。単体のSearch／Fetchは、HTTP 200で空ではない結果またはコンテンツが返った場合だけ課金される。どちらの経路でも、失敗した検索や空の検索結果は課金対象外だ。

独自パーサーなしでファイルをアップロードする

Files APIでは、ファイルを一度アップロードし、後からfile_idで参照できる。最小構成は次のとおりだ。

curl https://api.deepseek.com/files \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -F purpose="rich_layout_recognition" \
  -F file="@report.pdf"
# -> {"id": "file-api-xxxxxxxxxxxxxxxx", ...}

# then reference it in chat (Chat Completions shape):
# {"model": "deepseek-flash", "messages": [{"role": "user",
#   "content": [{"type": "text", "text": "Compare this with today's numbers"},
#   {"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"}]}]}

purposeが処理方法を決める。ドキュメントの場合はfileフィールドより先に送らなければならない。user_dataは画像（JPEG、PNG、GIF、WebP）、プレーンテキスト、スプレッドシート、電子書籍に対応する。text_recognitionはPDF、Word、PowerPointと画像をテキストだけに変換し、rich_layout_recognitionはテキストに加えて、表や段組みの図も返す。PDFをuser_dataとしてアップロードするとHTTP 400になり、解析済みのドキュメントを画像として再利用したり、後からダウンロードしたりすることはできない。

ファイルはAPIキーではなくアカウントに紐づく。同じIDをOpenAI互換とAnthropic互換の両方のファミリーで利用できるが、後者ではanthropic-beta: files-api-2025-04-14ヘッダーが必要になる。解析はアップロード中に行われるため、file_idが返るのは処理が成功した後だ。

組み込みツールと単体のSearch／Fetchを使い分ける

会話の中で検索やページ読み込みをモデルに判断させたいなら、組み込みツールを使う。コード側で実行タイミングを制御したい場合は、Search & Fetch guideの単体APIが向いている。ランキング付きの検索はPOST https://api.deepseek.com/v1/tools/searchで実行でき、最大50件の結果、rerank_scoreは0〜3（1.5以上が高品質）、authorityは0〜4で返る。1つのURLをMarkdownに変換するFetchはPOST https://api.deepseek.com/v1/tools/fetchを使う。なお、単体Searchはまだ画像検索に対応していないが、Webツールは対応している。

レート制限はアカウント単位で、SearchとFetchは別々に管理される。Searchは100 QPS、Fetchは25 QPSに加えてドメインごとのFetch上限があり、超過するとHTTP 429が返る。408、429、5xxはリトライし、それ以外の4xxはリクエストを修正する。単体Searchでは、クエリ演算子（site:、-site:、"exact phrase"、lang:、after:／before:）も利用できる。

実際にかかる料金

ツール料金はトークン料金に加算される。SearchとFetchはそれぞれ成功したリクエスト1,000件あたり0.75ドル。OCR、ASR、TTSにも個別のツール料金があり、期間限定のプロモーションについては発表ページに詳しく記載されている。countを変更すると結果の件数は変わるが、料金は変わらない。

開発者による料金比較では、DeepSeekの検索は1,000件あたり約0.75ドル。OpenAIとClaudeの検索は1,000件あたりおよそ10ドルとされており（@berryxia）、ツール料金だけで約13倍の差がある。

クエリ1件の回答なら、ツール料金は1セント未満だ。思考モードで検索8回、ページを6回開くタスクなら、検索8件とFetch 6件として計上されるが、トークン料金を除けばそれでも2セント未満に収まる。一方で、エージェントが検索を何十回も繰り返すと、0.75ドル単位の料金はすぐに膨らむ。成功した呼び出し数を基準に予算を組み、深掘り検索の深さに上限を設けること。最終的なusageオブジェクトからtool_searchとtool_fetchを記録しよう。なお、そこにあるweb_search_requestsは表示用であり、課金対象の件数ではない。

リリース前の確認事項：引用、安全性、デモ

Web Tools guideによると、引用はURL、タイトル、引用テキストを含むweb_search_result_locationブロックとして返る。ストリーミング時はcitations_deltaイベントになり、1つのテキストブロックに含められるURLは最大1件。後続リクエストで引用をそのまま返しても無視される。ターンをまたいでsignatureフィールドとツールブロックを改変せず保持することも重要だ。読み込んだページはsignatureから復元され、signatureが無効または欠落していても処理自体は成功するが、ページ内容は破棄される。チャットボットガイドのサンプルトレースでは、ツール実行後に入力トークンが40から9,078まで増え、そのうち4,096トークンはキャッシュから提供されている。検索によって履歴が膨らむことを前提に、コンテキストを設計したい。

公開アプリでは、DeepSeekが安全性チェックを必須としており、モデレーション、モデル登録、AI生成コンテンツのラベル付けは開発者に委ねられている。組み込みの審査は最初のチェックとして使い、refusalの停止理由は明示的に処理すること。ページが審査に通らない場合はurl_not_allowedが返るが、そのFetchも課金対象になる。チャットデモは配線の参考になるものの、すべてブラウザー内で動作する構成だ。本番環境へ出す前に、独自のバックエンドを用意しよう。

よくある質問

毎回必ず検索するようモデルに指示できますか？

できない。ツールを実行するかどうかはモデルが判断し、tool_choiceでWebツール名を指定すると400が返る。

Web検索とファイルアップロードに対応するモデルとエンドポイントは？

Messages、Responses、Chat Completionsの各APIでdeepseek-flashを利用できる。ファイルのfile_id参照は、OpenAI互換とAnthropic互換の両ファミリーに対応する。

アップロードしたファイルとWeb検索を組み合わせられますか？

できる。公式に案内されているチャットボットの構成でも、ファイルのコンテキストと、引用付きのサーバー側検索を組み合わせている。

一般的なエージェントのタスクでは、検索は何回発生しますか？

単純な回答なら、数件のクエリを含む1回の呼び出しで済む。思考モードを使った調査では、最大でおよそ20回のツール呼び出しになることがある。タスクごとにtool_searchとtool_fetchを計測しよう。組み込みツールはクエリまたはページ単位、単体APIは成功したリクエスト単位で課金され、どちらも1,000件あたり0.75ドルだ。

まずはデモで組み込み検索を1回実行し、ファイルを1つアップロードしてみよう。最終的なusageオブジェクトにあるtool_searchとtool_fetchのカウンターを確認してから、タスクごとのツール料金が、独自にTavilyやSearXNGのレイヤーを運用するより安いか判断すればよい。