DeepSeek API の接続自体は複雑ではありません。実際につまずきやすいのは 3 点です。キーがどのプラットフォームに属するか、Base URL を最後まで正しく書いているか、モデル名が現行バージョンかどうか。多くの「つながらない」はモデル能力の問題ではなく、資格情報とアドレスがかみ合っていないことが原因です。
本記事では、登録、チャージ、キーの作成から始め、curl と Python の初回呼び出しを順に行い、その後にストリーミング出力、thinking モード、max_tokens、よくあるエラーを説明します。一通り実行すれば、接続経路はほぼ通せるはずです。
注記：DeepSeek はその権利者の商標です。本記事は DeepSeek 公式とは提携・所属関係にありません。モデル名、パラメータ、上限はバージョンによって変わる場合があります。本記事は 2026 年 10 月時点の公式ドキュメントで一般的な形を例にしており、最終的には公式ドキュメントとモデル価格を基準にしてください。
一、接続前に 4 つの対象を区別する
API 接続の失敗は、モデル能力ではなく、次の 4 つの対象がそろっていないことが大半です。
| 対象 | 役割 | 最も間違えやすい点 |
|---|---|---|
| アカウント | 残高、請求、キーの帰属を決める | A プラットフォームのキーに B プラットフォームのアドレスを設定する |
| API キー | 身元の証明 | コピー時に空白、改行、引用符が入る |
| Base URL | リクエストの送り先 | /v1 を書き忘れる、公式アドレスとゲートウェイアドレスを混ぜる |
| モデル名 | リクエストの model フィールド |
古い記事の期限切れの名前を流用する |
覚え方は簡単です。キーと Base URL は必ず対で使います。公式キーには公式入口だけ、ゲートウェイキーにはゲートウェイ入口だけを組み合わせてください。混ぜると通常は 401 が返ります。
二、登録、チャージ、キーの作成
公式のオープンプラットフォームを例にすると、順序は次のとおりです。
- DeepSeek のオープンプラットフォームを開き、登録してログインします。
- 画面の案内に従って必要な確認を完了し、チャージページへ進みます。
- 最初は少額をチャージし、着金を確認してからバッチ処理を実行します。
- API Keys ページで新しいキーを作成し、用途が分かる名前を付けます。たとえば
deepseek-test、deepseek-prodです。 - キーをコピーしたらすぐにパスワードマネージャーまたはサーバー側の環境変数へ保存します。ページを閉じると完全な値は通常表示されません。
- テスト用と本番用に別々のキーを作り、予算または使用量の通知を設定します。
ZSQH AI Gateway を使う場合も流れは似ています。登録ページでアカウントを作成し、コンソールでキーを作成してチャージし、本記事の後半にある OpenAI 互換の方法で呼び出します。両方で同じキーを共用しないでください。問題が起きたときに、残高、レート制限、設定ミスのどれなのか判断しにくくなります。
三、Base URL とモデル名：確認してからコードを書く
公式ドキュメントが現在示している OpenAI 互換の入口は https://api.deepseek.com で、チャット補完のパスは /chat/completions です。古いチュートリアルには https://api.deepseek.com/v1 と書かれているものもあります。利用できるかは公式ドキュメントの現在の説明を基準にしてください。不明な場合は、まず公式サンプルのアドレスで通してください。
| 項目 | 公式への直結 | ZSQH AI Gateway |
|---|---|---|
| Base URL | https://api.deepseek.com |
https://ai.zhongshangqihang.com/v1 |
| チャットのパス | /chat/completions |
/v1/chat/completions |
| キーの入手元 | 公式オープンプラットフォーム | ゲートウェイのコンソール |
| モデル名 | 公式ドキュメントを基準 | サイト内のモデル価格を基準 |
| 向くケース | DeepSeek のみを使い、公式のアクセスと支払いが順調 | 統一入口、複数モデル、人民元の請求が必要 |
2026 年 10 月時点で、公式ドキュメントに記載されているモデル名は deepseek-flash と deepseek-v4-pro です。古い記事にある deepseek-chat、deepseek-reasoner が引き続き使えるとは限りません。記憶でモデル名を入力せず、呼び出し前に公式ドキュメントまたはサイト内の価格ページと照合してください。
四、最初の curl：まず最小リクエストを通す
まず thinking を無効にして、変数を減らします。公式入口の例です。
export DEEPSEEK_API_KEY="sk-あなたのキー"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"messages": [{"role": "user", "content": "OK とだけ返してください"}],
"thinking": {"type": "disabled"},
"max_tokens": 32
}'
200 が返り、choices[0].message.content に内容があれば、キー、Base URL、モデル名の 3 つが正しいと分かります。ゲートウェイに切り替える場合は、URL を https://ai.zhongshangqihang.com/v1/chat/completions に置き換え、ゲートウェイのキーに変えます。
thinking は DeepSeek の拡張パラメータで、すべての OpenAI 互換サービスが対応しているわけではありません。ゲートウェイが対応していない場合はこのフィールドを外すか、ゲートウェイのドキュメントに従って対応するパラメータに変更してください。
五、Python の初回呼び出し：OpenAI SDK を使う
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com", # ゲートウェイでは https://ai.zhongshangqihang.com/v1
)
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "あなたは日本語の技術アシスタントです。簡潔に回答してください。"},
{"role": "user", "content": "ベクトルデータベースとは何かを 3 文で説明してください。"},
],
max_tokens=512,
extra_body={"thinking": {"type": "disabled"}},
)
print(resp.choices[0].message.content)
print(resp.usage)
OpenAI SDK は thinking フィールドを認識しないため、extra_body で渡します。通ったらまず usage を確認してください。入力と出力がそれぞれ何 Token か、キャッシュヒットが返るか、推論内容が別に計上されるか。これらのデータは「速い気がする」よりも、後のコスト設定とタイムアウト設定の役に立ちます。
六、ストリーミング出力と reasoning_content
thinking は既定で有効で、既定の強度は high です。有効にすると、レスポンスに reasoning_content が現れ、最終的な本文 content と同じ階層に並びます。ストリーミングでは delta.reasoning_content に分割されて返ります。
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "CSV を読み込む Python のサンプルを書いてください"}],
stream=True,
max_tokens=4096,
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
reasoning, answer = [], []
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None):
reasoning.append(delta.reasoning_content)
if delta.content:
answer.append(delta.content)
print("思考プロセス：", "".join(reasoning))
print("最終回答：", "".join(answer))
マルチターンの会話で、リクエストに tools が含まれる場合、前のターンの reasoning_content を完全に返送する必要があります。含めないと 400 が返る場合があります。tools がない場合は省略でき、サーバー側で無視されます。エンドユーザー向けの画面では、思考内容は折りたたんで表示し、既定で全部展開しないことをおすすめします。
七、max_tokens、temperature、thinking の設定
| タスク | thinking | 推奨の開始値 | 説明 |
|---|---|---|---|
| 疎通テスト | 無効 | max_tokens 32〜128 | 短い返答だけが必要 |
| 分類、抽出 | 無効 | 256〜1024 | 出力を構造化し、思考の負荷を減らす |
| カスタマーサポート、執筆 | 有効 | 1024〜4096 | 効果を見ながら effort を調整 |
| コード、複雑な推論 | 有効 | 4096 以上 | 思考プロセスに十分な予算を確保 |
公式ドキュメントの現在の記載では、コンテキスト長は 1M Token、max_tokens の範囲は 1 から 384K です。設定しない場合、非 thinking は既定 8K、thinking は既定 64K、reasoning_effort が max のときは既定 128K です。これらの値は調整される可能性があるため、公式ドキュメントを基準にしてください。
thinking モードでは、temperature、presence_penalty、frequency_penalty は効きません。変更してもエラーにはなりませんが、結果も変わりません。max_tokens も低くしすぎないでください。思考内容が出力予算を使うため、予算が小さいと本文を書き終える前に切れることがあります。
八、401、402、429、タイムアウトの切り分け
| 現象 | よくある原因 | 対処 |
|---|---|---|
| 401 | キーの誤り、Bearer の欠落、キーと Base URL が別プラットフォーム | キーをコピーし直し、ヘッダーを確認し、入口の一致を確認 |
| 402 | アカウント残高の不足 | チャージしてから再試行。コードを直す前に残高を確認 |
| 429 | リクエストが速すぎる、同時実行または QPS の超過 | 同時実行の削減、指数バックオフ、プロジェクト単位のキー分割 |
| 400/422 | パラメータ、モデル名、コンテキストが不正 | エラーメッセージを見て、モデル名と max_tokens を確認 |
| タイムアウト | ネットワーク、長い出力、thinking の所要時間 | 接続と読み取りのタイムアウトを分け、出力を制限 |
| 500/503 | 上流サービスのエラーまたは過負荷 | 少し待ってからバックオフ再試行 |
429 の同時実行上限はアカウント単位で集計され、キーごとに均等配分されるわけではありません。同じアカウントの複数キーは割当を共有するため、「キーを増やす」だけでは同時実行の制限を回避できません。公式ドキュメントでは、10 分以内に推論が始まらないと接続が切断されることも説明されています。クライアントはこの状況を識別して再試行できる必要があります。
九、キーの安全：公開前に最低 5 つ
- キーはサーバー側の環境変数またはシークレット管理サービスにだけ置き、フロントエンド、リポジトリ、ログに書かない。
- テスト、ステージング、本番でそれぞれ別のキーを使い、問題時にすぐ特定・停止できるようにする。
- 残高の通知または利用上限を設定し、異常な呼び出しでは先に損害を止める。
- ログにはキーの先頭部分またはフィンガープリントだけを記録し、完全な値は残さない。
- 人事異動や漏えいの疑いがあるときは即座にローテーションし、直近の使用量を確認する。
十、公式からゲートウェイへ：変更は 2 か所
移行時はまず base_url と api_key を変更し、モデル名はゲートウェイの価格ページで再確認します。それ以外のリクエストボディはできるだけ変えません。同じ実プロンプトの組で出力、所要時間、usage を比較し、3〜7 日観察してから本番へ切り替えてください。公式への直結を予備経路として残すと、問題時に素早く戻せます。
統一入口や複数モデルの請求が必要な場合は、ZSQH AI Gateway でテストキーを作成してください。価格と利用可能なモデルはモデル価格に記載されています。
関連記事：
よくある質問
Base URL に /v1 を付けるべきですか？
公式ドキュメントの現在のサンプルを基準にしてください。公式の OpenAI 互換入口は https://api.deepseek.com と書かれ、チャットのパスは /chat/completions です。ゲートウェイは通常 /v1 の接頭辞を使います。古いチュートリアルから推測せず、まず curl で完全なアドレスを 1 回試してください。
401 はキーの誤りですか、残高不足ですか？
401 は認証の失敗です。キーが正しいか、Bearer が付いているか、キーと Base URL が同じプラットフォームかを優先して確認してください。残高不足は通常 402 を返すため、両者を混同しないでください。
最初の呼び出しで thinking を有効にすべきですか？
まず無効にすることをおすすめします。最短のリクエストで経路が通ることを確認してください。キー、アドレス、モデル名に問題がないと分かってから、タスクに応じて有効にし、低めの reasoning_effort から試します。
max_tokens はいくつが適切ですか？
まずタスクに十分な値を設定し、通ってから絞り込みます。分類と抽出は数百から始め、長文とコードは数千を確保します。thinking モードでは思考内容の分の予算が必要で、小さすぎると本文が途中で切れます。
公式キーをそのままゲートウェイのアドレスに設定できますか？
できません。公式キーは公式入口にだけ対応し、ゲートウェイキーはゲートウェイ入口にだけ対応します。混ぜると通常 401 が返ります。入口を切り替えるときは、キーと Base URL を対で変更してください。
