AI 教學

豆包 API 入門攻略:從申請金鑰到跑出第一個請求

豆包 API 是火山引擎火山方舟平台的模型呼叫服務,相容 OpenAI SDK 格式,遷移成本低。這篇用可執行的步驟帶你完成開通、建立金鑰、發出第一個對話請求與串流輸出,並整理模型挑選、計費與新手常見錯誤。

陳柏宇陳柏宇
熱度:760
豆包 API 入門攻略:從申請金鑰到跑出第一個請求

豆包(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 這些第三方模型都能一起呼叫。跑一個專案常常只要一組金鑰、一個網址就能打通。

開始前要準備的三件事

動手寫程式之前,先把這三項處理好,後面會少繞很多路。

  1. 開通火山引擎帳號並完成實名認證。 火山引擎是中國大陸平台,註冊需要手機號,付費支援支付寶與微信。沒有帳號就進不了主控台。
  2. 建立專案,建立 API Key。 金鑰是綁在專案底下的,不是整個帳號共用。官方主控台的路徑是「API Key 管理」,產生後記得先複製存好,畫面關掉就看不到了。
  3. 確認你要用的模型 ID 或接入點 ID。 這是最容易搞錯的一步。預置模型通常直接用官方 Model ID(例如文件裡示範的 doubao-seed-2-1-pro-260628),但如果你是自己建的推論部署,用的就是另一個「接入點 ID」。兩者不能混用。

步驟一:安裝 SDK 並設定金鑰

火山方舟提供官方 Python SDK,也可以用 OpenAI 的 SDK 來接。先選一種。

用官方 SDK 的話:

  1. 在終端機安裝套件:pip install volcengine-python-sdk
  2. 把金鑰設成環境變數,不要寫死在程式碼裡。命名為 ARK_API_KEY。
  3. 在程式開頭初始化客戶端,帶入 base_url 與剛才的 api_key。

用 OpenAI SDK 的話: 直接 pip install openai,然後把 base_url 指向方舟的網址、api_key 填你的金鑰即可。這也是官方文件明確支援的相容路徑。

金鑰屬於敏感資訊。官方提醒金鑰是綁專案的,可以限制它能呼叫哪些模型、哪些接入點,甚至限制來源 IP。放進 Git 之前務必用環境變數或密鑰管理服務收好。

步驟二:發出第一個對話請求

環境好了就來跑第一句話。以下用最常見的對話補全接口示範,邏輯跟 OpenAI 幾乎一樣。

  1. 準備 messages 陣列,格式是每則訊息帶 role(system/user/assistant)與 content。
  2. 指定 model,填你在主控台確認過的模型 ID。
  3. 呼叫 chat.completions 接口,把 messages 送出去。
  4. 從回傳結果裡讀 choices[0].message.content,那就是模型回覆的文字。

跑通之後,建議先做一件事:把回應印出來確認內容正常,再接到實際產品裡。很多新手卡住的原因不是程式錯,而是模型名稱填成了主控台上的「顯示名稱」。顯示名稱是給人看的,程式要用的是 Model ID,這點官方文件特別標註過。

步驟三:打開串流輸出,讓回覆即時出現

如果你的產品需要讓使用者看到字一個一個跳出來,就要用串流。差別只在請求時把 stream 設為 True。

  1. 在請求參數裡加上 stream: True。
  2. 用迴圈逐段讀取回應,每一段解析後取 delta 裡的 content。
  3. 把拿到的片段即時印出或推送到前端。

這裡有個容易忽略的坑:官方提醒,串流即使在 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 的入門攻略,想先從聊天介面熟悉這套模型的人可以先去看那篇。

分享這則新聞

來源

相關 AI 新聞

Claude Code Mods 是什麼?用 TypeScript 改寫 AI 編程助手
AI 教學

Claude Code Mods 是什麼?用 TypeScript 改寫 AI 編程助手

Anthropic 為 Claude Code 引入 mods,用幾行 TypeScript 就能改寫這個 AI 編程助手的行為、介面與內建功能。本文說明 mods 怎麼運作、能改到什麼程度,以及它的權限風險。

熱度:880
如何設定 Grok Team Bots:情境、外掛與 Slack
AI 教學

如何設定 Grok Team Bots:情境、外掛與 Slack

Grok Team Bots 讓整個團隊共用一個 AI 代理,而設定它其實就四件事:情境、外掛、憑證與記憶。這篇逐步說明每個選擇,讓你的第一個共享 bot 第一天就派得上用場。

熱度:1,020
Grok 的 NSFW 設定怎麼開?官方位置、方案限制與內容規則
AI 教學

Grok 的 NSFW 設定怎麼開?官方位置、方案限制與內容規則

Grok 在帳號設定中提供成人內容選項,行動版與網頁版入口不同,且需要特定訂閱資格與年齡驗證。本文客觀說明官方設定位置、開啟後仍會被擋下的內容範疇、與隱私設定的差異,以及找不到選項時的排查順序。

熱度:900
怎麼追蹤品牌在 AI 搜尋裡的提及?從手動到自動的完整做法
AI 教學

怎麼追蹤品牌在 AI 搜尋裡的提及?從手動到自動的完整做法

AI 平台不提供曝光數據,傳統工具看不到品牌在 AI 答案裡的提及。本文說明該追蹤的是出現頻率而非排名,並拆解提及、引用、推薦三個層次,帶你建立提示詞清單、用手動抽查與 Perplexity API 完成監測。

熱度:760