DeepSeek API 使用指南：從取得金鑰到跑通呼叫

一切從一條報錯開始，這個夏天我親眼見了兩次。同事照某篇教學敲了 pip install deepseek-api，pip 回了他一整屏紅字。另一回是裝好了、範例一跑，伺服器回 Model Not Exist——因為教學裡寫的 deepseek-chat，2026 年 7 月 24 日就跟 deepseek-reasoner 一起退役了。這兩種失敗都不怪鍵盤前的人：教學過期了，DeepSeek API 已經往前走了。

本文全部對齊 2026 年 8 月的現行口徑：真正能解析的模型名、真實存在的取金鑰流程、GA 版上線的參數。一篇講完從零到生產級呼叫鏈——金鑰、第一次呼叫、串流、思考模式、多輪對話、結構化輸出、限流。順帶一張糾正表，把流傳甚廣的教學還在教錯的東西逐條對清。

DeepSeek API 是什麼

DeepSeek API 是一個說兩種業界標準方言的 chat 介面：OpenAI 格式和 Anthropic 格式。雙相容就是它的全部設計哲學——你不需要裝新 SDK、學新報文格式、重寫任何東西，把現有 OpenAI 用戶端指到另一個 base URL、換一個模型字串就完事。會調 GPT 就會調 DeepSeek。

三個官方網域各司其職，分清它們比想像中重要——這個主題的搜尋結果裡至少混著八個仿冒站（deep-seek.com、deepseekv4pro.com 之流），既不是文件也不是控制台：

網域	用途
platform.deepseek.com	控制台：建金鑰、查餘額、看用量
api-docs.deepseek.com	文件與指南
api.deepseek.com	你的程式真正請求的端點

現行模型名，以及它們背後實際指向的 checkpoint：

模型字串	實際 checkpoint	定位
`deepseek-v4-flash`	V4-Flash-0731	快且便宜，日常主力
`deepseek-v4-pro`	V4-Pro-0813	深度推理旗艦
`deepseek-v4-flash-vision-exp`	實驗版	文字+圖像輸入

這個映射是刻意設計的：呼叫名保持穩定，DeepSeek 在背後把它指到最新 checkpoint。但有兩個名字不再解析：deepseek-chat 和 deepseek-reasoner，2026 年 7 月 24 日全部退役。任何還在敲這兩個名字的教學，描述的都是一個已經不存在的產品。（模型規格、跑分和完整價格見站內 DeepSeek V4 全解。）

取得 DeepSeek API 金鑰

認證就是一個普通的 HTTP Bearer token——一個字串、一個請求標頭。取得方式：登入 platform.deepseek.com，進 API Keys 頁，點建立，立刻複製。金鑰只顯示一次。流程到此為止，沒有更多儀式。

有兩件事值得說透，因為這兩件事上噪音很大。

第一：沒有 OAuth 流程、沒有企業認證表單、沒有權限範圍勾選。有些流傳很廣的教學描述了一套「OAuth 2.0 雙階段認證+實名驗證」——那套流程不存在。哪篇指南要你設定 OAuth 憑證，你讀到的就是小說。

第二：把金鑰當密碼保管，因為它就是能花錢的密碼。生產環境的標準紀律：

# .env —— 永不寫死、永不提交
DEEPSEEK_API_KEY=sk-your-key-here

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("DEEPSEEK_API_KEY")
if not api_key:
    raise RuntimeError("Missing DEEPSEEK_API_KEY")

金鑰只留在伺服器端。發到瀏覽器或打包進 App 的金鑰就不再是秘密了——那是捐款。

第一次呼叫 DeepSeek API

官方首個呼叫範例是裸 HTTP 寫的，值得慢慢讀一遍，因為每個欄位之後都會以 SDK 的形態再出現——這段 curl 我到現在接到任何新帳號都先跑一遍：一槍驗證金鑰、網路、模型名三樣全通，之後出了問題才好排查：

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
        "model": "deepseek-v4-pro",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Hello!"}
        ],
        "thinking": {"type": "enabled"},
        "reasoning_effort": "high",
        "stream": false
      }'

端點是 api.deepseek.com 上的 POST /chat/completions。messages 按角色堆疊——先 system 人設，再使用者輪次。thinking 打開思維鏈開關，reasoning_effort 設定思考強度，stream: false 表示等整個 JSON 回應一次回來。

Python 版

「OpenAI 相容」在實際開發裡買到的東西是這個——裝標準 OpenAI SDK，不是任何第三方「deepseek」套件（其中幾個是非官方的，有一個著名的是純虛構的）：

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",   # 那個轉接頭
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "用兩句話解釋 HTTP cookie。"},
    ],
)
print(response.choices[0].message.content)

遷移只改兩行：base_url 和模型字串。其餘一切——重試、型別、串流助手——都是你現有 OpenAI 程式換個識別證繼續上班。用 Anthropic SDK 的程式庫同理，指到 https://api.deepseek.com/anthropic。

串流輸出

設 stream=True，回應以伺服器推送事件（SSE）到達：一串 JSON 塊，每塊帶著裝有幾個新 token 的 delta。頭幾個詞在模型想完全部內容之前就冒出來——這就是聊天「感覺活著」和「感覺在下載檔案」的差別。

stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "寫一首關於延遲的俳句。"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

串流與否，回應裡的 usage 欄位都會報 prompt_tokens 和 completion_tokens——你的帳單就是從這兩個數字算出來的。現在就養成記日誌的習慣，下文 token 一節講它們意味著什麼。

串流有兩個第一週就回本的習慣——我自己都是付過學費才養成的。給每個請求設明確逾時——一條卡死的連線佔著槽位不放，跟一個特別慢的模型沒有區別，重連好過乾等。串中途斷掉時，重送整個請求：半截輸出只是展示材料，伺服器不記得它，沒有續傳 token 可送。低單價的請求讓這兩個習慣都無痛——這也是「先在 flash 檔上把業務跑起來、實測出差距再升 pro」的一個靜默論據。

思考模式與 Effort：真正要緊的兩個旋鈕

跟舊 API 的一個重大差異：思考模式預設開啟，預設檔位 high。回答之前，模型先走一遍思維鏈再作答——難題準確率上去，延遲跟著上去。

effort 參數是三個真實檔位的油門。low 是市區代步——快速回答、最少盤算。high 是高速巡航，預設甜點位。max 是賽道模式：給證明題、架構決策、疑難除錯用滿額推理預算。還有個值得知道的怪癖——請求 medium 或 xhigh，平台都會映射成 high。映射表直接來自思考模式指南：

你請求的	模型實際跑的
low	low
medium	high
high	high
xhigh	high
max	max

簡單呼叫想關掉思考，傳開關即可——注意 Python 細節：OpenAI SDK 不認識這個欄位，所以要塞進 extra_body：

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "9.11 和 9.8 哪個大？"}],
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)

兩個多數教學跳過的深水細節。

其一，思考模式之內，取樣參數——temperature、top_p、presence_penalty、frequency_penalty——全部無效。API 會靜默收下（為了相容既有軟體）然後忽略。我曾為此安靜地耗掉一個下午——調 temperature 死活沒變化，最後在文件裡翻到那行字。你遇到一樣的情況：就是這個原因，不是你程式的 bug。

其二，思維鏈從 reasoning_content 欄位回傳，跟 content 並排。後續輪次裡，歷史 reasoning_content 在請求不帶 tools 參數時會被伺服端忽略——所以放心把舊推理從儲存的上下文裡剝掉，一點不虧。

多輪對話：沒有記憶的服務生

chat 端點沒有記憶，一點都沒有。每個請求都是一位全新顧客：伺服端只讀你送來的 messages 陣列，作答，然後把這一桌忘得乾乾淨淨。所謂多輪對話，是你——用戶端——自己留著對話記錄，每輪把整桌內容重新唸給服務生聽。

messages = [{"role": "user", "content": "世界上最高的山是什麼？"}]

response = client.chat.completions.create(
    model="deepseek-v4-flash", messages=messages
)
messages.append(response.choices[0].message)   # 服務生的回答

messages.append({"role": "user", "content": "第二高呢？"})
response = client.chat.completions.create(
    model="deepseek-v4-flash", messages=messages
)
print(response.choices[0].message.content)

第二輪送出去三條：原始問題、存下來的回答、新問題。這個模式——追加回答、追加新輪次、全量重送——就是對話記憶的全部祕密，也是長 agent 工作階段每輪成本線性上漲的原因。（讓這些越長越長的對話記錄保持高效的提示詞策略，見提示詞技巧。）

結構化 JSON 輸出

當輸出要餵給解析器而不是人眼時，自由散文就是 bug。JSON 模式鎖死輸出形狀，靠三條規則：設回應格式、在提示詞裡寫 "json" 這個詞並給範例、設 max_tokens 上限防止長回答把物件截斷在半路。

system_prompt = """
The user will provide some exam text. Please parse the "question"
and "answer" and output them in JSON format.
EXAMPLE INPUT:
Which is the highest mountain in the world? Mount Everest.
EXAMPLE JSON OUTPUT:
{"question": "...", "answer": "..."}
"""

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "世界上最長的河是什麼？尼羅河。"},
    ],
    response_format={"type": "json_object"},
    max_tokens=512,
)
print(response.choices[0].message.content)

提示詞裡漏了範例，品質會掉；漏了 max_tokens，一個話癆回答可能停在半個花括號上——那是只在生產環境才炸給你看的 json.loads 崩潰。

限流與 user_id 救生索

並發按帳號計數，跟用哪把金鑰發的請求無關。想像一家餐廳：你的帳號有固定桌數，每個在途請求從發出到收完最後一個位元組都佔一張桌。

模型	每帳號並發上限
deepseek-v4-pro	500
deepseek-v4-flash	2,500
deepseek-v4-flash-vision-exp	2,500

越過線就是 HTTP 429——退避重試，別硬衝。要更多桌子？擴容申請免費，平台按真實業務量匹配額度。現行數字以限流頁為準。

如果你在一個帳號下服務很多終端使用者，user_id 把大堂隔成包廂。按請求傳它——字母數字連字號底線、最長 512 字元、別塞隱私資訊——平台按身分隔離三件事：內容安全處理、KV 快取（一個使用者快取過的上下文絕不滲進另一個人的）、排程。OpenAI SDK 裡它也走 extra_body：

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "你好！"}],
    extra_body={"user_id": "customer-8801"},
)

對提額帳號，每個 user_id 還有各自的並發上限——一個失控租用戶餓不死其他人。

Token 與帳單

計費按 token，心算很友善：1 個英文字元約 0.3 token，1 個漢字約 0.6。一篇 1000 詞的英文文章，模型還沒作答就先吃掉約 1300 輸入 token。精確數字永遠以回應 usage 欄位回傳的為準——要對帳就看它，別信任何估算器；官方文件另附 tokenizer demo 供離線計算。圖像輸入按尺寸走一套公式、每圖有上限。

每個 token 多少錢、峰時離峰怎麼算——那是定價問題，有自己的答案頁，V4 全解帶著現行價表和生效日期。

Chat API 之外

/chat/completions 是正門，不是整棟房子。文件裡圍繞它還有：

GET /models——列出你的金鑰能摸到哪些模型，含 owner 與可用性
GET /user/balance——錢包查詢，給儀表板和消費告警用
Files API——上傳一次、按 ID 引用（免費）
Context Caching——自動前綴快取，命中價是未命中的三十分之一
FIM completion——填空中段，給程式碼編輯流用
Responses API——更新的回應格式，8 月 13 日起 GA
Anthropic 格式介面——同一批模型，…/anthropic 路徑

還有一扇完全不用寫程式的門：編程 Agent。Claude Code、GitHub Copilot、OpenCode 都能純設定把 DeepSeek 設為後端模型。Claude Code 接入教學把環境變數配方從頭到尾走了一遍——如果你的目標是「DeepSeek 進我的終端機」，那就是繞過上面一切的捷徑。

2026 年的常見坑

上面講的一切對撞還在流傳的一切，一張表收口：

舊教學說	2026 年現實
`pip install deepseek-api`、`from deepseek_api import DeepSeekClient`	不存在這個官方套件。`pip install openai`，`base_url` 指 `https://api.deepseek.com`
`model="deepseek-chat"` / `"deepseek-reasoner"`	2026 年 7 月 24 日退役。用 `deepseek-v4-flash` 或 `deepseek-v4-pro`
OAuth 2.0、實名驗證、企業認證才可用	platform.deepseek.com 拿 Bearer 金鑰，僅此而已
JWT 簽章、HMAC 請求簽章	都不存在。`Authorization: Bearer` 請求標頭
思考模式裡調 temperature	思考開啟時靜默無效
把 deep-seek.com / deepseekv4pro.com 當官網	官方三件套：platform.deepseek.com、api-docs.deepseek.com、api.deepseek.com

比所有條目更老的元規則：先看教學的發布日期，再看它的程式碼區塊。這個 API 七月退役了模型名、八月調了價——在那之前寫的任何東西都是考古材料。

常見問題

DeepSeek API 怎麼串接？三步：在 platform.deepseek.com 的 API Keys 頁建金鑰；裝 OpenAI SDK（pip install openai）；用 base_url="https://api.deepseek.com" 加你的金鑰建構用戶端。第一個呼叫就是標準的 chat completion，model="deepseek-v4-flash"。

DeepSeek API 用什麼 SDK？沒有專用 SDK。它同時相容 OpenAI 和 Anthropic 兩家 SDK——複用其中任何一個，只改 base URL（https://api.deepseek.com 或 https://api.deepseek.com/anthropic）和模型名。

DeepSeek API 的 base URL 是什麼？OpenAI 格式用 https://api.deepseek.com；Anthropic 格式用 https://api.deepseek.com/anthropic。對話請求送 POST /chat/completions。

deepseek-chat 還能用嗎？不能。deepseek-chat 和 deepseek-reasoner 已於 2026 年 7 月 24 日退役。替代品是 deepseek-v4-flash 和 deepseek-v4-pro，自動指向最新 checkpoint（V4-Flash-0731 和 V4-Pro-0813）。

API 免費嗎？怎麼查餘額？按量付費，自動上下文快取能攤薄重複輸入的成本。即時餘額一個呼叫就有——GET /user/balance——每個回應的 usage 欄位給出逐次呼叫的 token 數供對帳。

限流多少？429 什麼意思？deepseek-v4-pro 並發 500，deepseek-v4-flash 和視覺模型並發 2500，按帳號計。429 表示越過上限：退避重試。更高上限可透過免費擴容申請拿到。

能用 Anthropic 格式的程式調嗎？能——Anthropic SDK 配 base_url="https://api.deepseek.com/anthropic"，模型名不變。工具定義和訊息結構都直接沿用。

從這裡出發三步走：拿一把金鑰，原樣跑通 curl 片段直到看到回覆，然後決定這個模型在你技術棧裡的位置——今晚先寫個腳本，還是讓編程 Agent 幹重活（Claude Code 接入教學）。相容介面真正的承諾不是哪個模型的跑分，而是：整合程式永遠是你的，模型變成一行就能換的決定。

Edward Wang