API 文檔白話解讀
官方 API 文檔寫得偏技術，這裡用日常語言解釋每個接口是幹什麼的、 什麼時候需要用。原文在 api-docs.deepseek.com。
為什麼需要這一頁。
官方文檔假設你懂 HTTP、JSON、token、流式傳輸。但大部分人只是想知道
「我要做個客服機器人，該調哪個接口」。這一頁回答那個問題，不重複文檔細節。
六個接口，人話版
对话补全
POST /chat/completions最常用的接口。你给它一串消息（谁说了什么），它返回下一条。聊天机器人、客服、问答都走这个。
大部分应用只需要这一个接口。
文本补全
POST /completions给它一段开头，它接着写。代码补全（FIM：中间填）走这个，因为它能让模型只补中间那段而不是从头写。
做 IDE 补全插件时才需要。
列出模型
GET /models返回当前可用的模型名。写死模型名容易过时，建议启动时拉一次。
调试时先跑这个确认模型名。
查余额
GET /user/balance返回账户余额。适合做「余额不足」告警。
余额低于阈值就发通知，避免半夜停服。
文件上传
POST /files上传文件后拿到一个 id，后续请求引用这个 id 而不是重新传内容。
适合反复引用同一份长文档的场景。
前缀续写
POST /beta/chat/completions给模型一个开头，强制它从这里继续。写代码骨架、续写 JSON 时有用。
这是 beta 接口，行为可能变。
最小可用示例
curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "你好"}]
}'
四個常見誤解
| 誤解 | 實際 |
|---|---|
| 「模型名要寫具體版本」 | 用 deepseek-chat / deepseek-reasoner 就好，具體版本會自動指向最新 |
| 「流式輸出更貴」 | 價格一樣，流式只是讓你早點看到字，不是多收錢 |
| 「上下文越長越貴」 | 按實際 token 計費，不是按上限。用多少算多少 |
| 「思考模式一定更好」 | 思考模式更貴更慢，簡單任務不需要 |