豆包(Doubao)是字節跳動旗下火山引擎自研的大模型,除了網頁與 App,開發者還能透過火山方舟平台用 API 接進自己的產品。這篇從申請金鑰開始,一路帶你把第一個請求跑起來,並整理上線前必須注意的費用與權限細節。
豆包 API 是什麼,跟網頁版差在哪
豆包 API 是火山引擎(Volcengine)推出的模型呼叫服務,走的是「火山方舟」這個平台。它跟你在豆包官網聊天用的東西共用同一批模型,但接口是給程式呼叫的,差別在於網頁版有人機介面、有對話歷史,API 則是你自己寫程式決定怎麼用、用在哪。
對開發者來說,最實用的地方是它相容 OpenAI 的 SDK 格式。也就是說,如果你之前接過 ChatGPT 的 API,只要換掉網址、金鑰與模型名稱,大部分的程式碼可以沿用,遷移成本相當低。根據火山引擎官方文件,方舟的資料面網址是 https://ark.cn-beijing.volces.com/api/v3,用的是專案層級的 API Key。
它托管的模型也不只豆包自家。除了 Seed 系列文本與推理模型,同一個平台上還放了圖像生成、影片生成、語音、嵌入與重排序模型,甚至連 DeepSeek、GLM、Kimi 這些第三方模型都能一起呼叫。跑一個專案常常只要一組金鑰、一個網址就能打通。
開始前要準備的三件事
動手寫程式之前,先把這三項處理好,後面會少繞很多路。
- 開通火山引擎帳號並完成實名認證。 火山引擎是中國大陸平台,註冊需要手機號,付費支援支付寶與微信。沒有帳號就進不了主控台。
- 建立專案,建立 API Key。 金鑰是綁在專案底下的,不是整個帳號共用。官方主控台的路徑是「API Key 管理」,產生後記得先複製存好,畫面關掉就看不到了。
- 確認你要用的模型 ID 或接入點 ID。 這是最容易搞錯的一步。預置模型通常直接用官方 Model ID(例如文件裡示範的
doubao-seed-2-1-pro-260628),但如果你是自己建的推論部署,用的就是另一個「接入點 ID」。兩者不能混用。
步驟一:安裝 SDK 並設定金鑰
火山方舟提供官方 Python SDK,也可以用 OpenAI 的 SDK 來接。先選一種。
用官方 SDK 的話:
- 在終端機安裝套件:
pip install volcengine-python-sdk - 把金鑰設成環境變數,不要寫死在程式碼裡。命名為
ARK_API_KEY。 - 在程式開頭初始化客戶端,帶入
base_url與剛才的api_key。
用 OpenAI SDK 的話: 直接 pip install openai,然後把 base_url 指向方舟的網址、api_key 填你的金鑰即可。這也是官方文件明確支援的相容路徑。
金鑰屬於敏感資訊。官方提醒金鑰是綁專案的,可以限制它能呼叫哪些模型、哪些接入點,甚至限制來源 IP。放進 Git 之前務必用環境變數或密鑰管理服務收好。
步驟二:發出第一個對話請求
環境好了就來跑第一句話。以下用最常見的對話補全接口示範,邏輯跟 OpenAI 幾乎一樣。
- 準備
messages陣列,格式是每則訊息帶role(system/user/assistant)與content。 - 指定
model,填你在主控台確認過的模型 ID。 - 呼叫
chat.completions接口,把messages送出去。 - 從回傳結果裡讀
choices[0].message.content,那就是模型回覆的文字。
跑通之後,建議先做一件事:把回應印出來確認內容正常,再接到實際產品裡。很多新手卡住的原因不是程式錯,而是模型名稱填成了主控台上的「顯示名稱」。顯示名稱是給人看的,程式要用的是 Model ID,這點官方文件特別標註過。
步驟三:打開串流輸出,讓回覆即時出現
如果你的產品需要讓使用者看到字一個一個跳出來,就要用串流。差別只在請求時把 stream 設為 True。
- 在請求參數裡加上
stream: True。 - 用迴圈逐段讀取回應,每一段解析後取
delta裡的content。 - 把拿到的片段即時印出或推送到前端。
這裡有個容易忽略的坑:官方提醒,串流即使在 HTTP 狀態碼回傳 200 之後,仍可能夾帶業務層級的錯誤。也就是說不能只看 200 就當成功,還要檢查事件裡的錯誤類型與請求 ID。上線前把這段錯誤處理寫進去,之後排查問題會省很多時間。
模型怎麼挑,看你的任務型態
方舟上的模型分幾個層次,挑錯了不是不能跑,是白花錢。官方目前列出的主力選項大致是這樣:
任務型態 | 建議模型 | 選它的理由 |
|---|---|---|
複雜推理、多步代理、看圖看影片 | Seed 2.1 Pro 系列 | 能力最完整,能吃圖像與影片輸入 |
日常助理、寫程式、一般代理 | Seed 2.1 Turbo 系列 | 品質與速度平衡,適合高頻呼叫 |
成本敏感的批次處理 | Seed 2.0 Lite | 支援文本、圖像、影片、音訊理解 |
追求吞吐量、預算最緊 | Seed 2.0 Mini | 主打單位成本,適合大量簡單請求 |
圖像生成與修圖 | Seedream 5.0 系列 | 高品質出圖,另有輕量版 |
影片生成 | Seedance 2.0 系列 | 文生影片,另有更快的版本 |
要注意的是,官方把「模型版本」和「服務等級」當成兩個獨立選擇。Turbo 不是 Fast,你選了 Turbo 模型,並不代表請求會自動走低延遲的 Fast 通道。這兩個是分開設定的。
費用怎麼算,別讓帳單嚇到自己
火山方舟的計費按詞元(Token)計算,輸入與輸出分開計價。除了標準的線上推論價,還有幾種會影響帳單的服務型態:
- 線上推論:一般互動式請求走這個,價格按模型與輸入長度分段。
- Fast 服務等級:低延遲通道,是不是有折扣要看模型與通道,不是每個模型都支援。
- 批次推論:這是獨立的批次服務,價格比線上便宜,但只有伺服器確認為批次的任務才適用。你在客戶端加參數或標頭,並不會讓普通請求變成批次價。
- 上下文快取:重複的長提示可以命中快取,命中部分另有折扣,價格比一般輸入低。
幾個官方明講的踩雷點:Coding Plan 用的是另一組專屬網址,如果你不小心用了按量付費的網址,就會繞過方案、產生額外費用。另外,快取重疊的部分需要自己去重,儲存也要按實際時長計價。上線前務必設定輸出上限、併發上限、逾時與重試次數,並開啟帳單提醒。
新手最常犯的三個錯誤
把這些先記起來,可以少踩幾次坑。
把顯示名稱當成 Model ID 填進去。 主控台上看到的名字是給人讀的,程式要填官方 Model ID 或接入點 ID,三種值不能互換。
以為金鑰可以跨專案共用。 一把金鑰只屬於一個專案,而且可以被模型、接入點、來源 IP 限制住。搬動接入點可能讓舊金鑰失效,遇到認證失敗先檢查這一點。
把媒體生成當成聊天接口呼叫。 圖像、影片、語音的生成是各自獨立的工作流程,不能因為都掛著豆包的名字就用對話接口去叫。嵌入這類能力有時候也得用原生協議,不能硬套 OpenAI 格式。
接下來可以玩什麼
把第一個請求跑通只是起點。接下來值得試的方向,是拿預置模型先驗證你想要的場景,確認效果與成本都合理,再考慮要不要建自己的推論部署。如果你要接的是多模態產品,Seedream 出圖、Seedance 出影片、加上 Seed 系列做推理,整條鏈可以在同一組金鑰下打通,這是方舟相對省事的地方。站上我們也整理了豆包網頁版與 App 的入門攻略,想先從聊天介面熟悉這套模型的人可以先去看那篇。






