開發者實戰：接入百度 AI 開放平台 API 的第一支應用

第一次接一個雲端 AI 平台的 API，卡住的地方通常不是演算法，而是授權。文件很長，端點很多，你只想知道那顆 token 到底從哪裡來、要放在哪裡。

這篇把百度 AI 開放平台的接入邏輯拆成三步講完，順便談 OCR、語音、NLP 三類介面該怎麼想，以及成本要怎麼控。程式碼只寫結構示意，實際端點與參數名請對照官方文件。

接 API 這件事，八成的時間會花在前面三十分鐘。憑證放哪、token 怎麼換、錯了要看哪個欄位。這三件事想通，剩下的都是查文件。

先分清楚你要接的是哪一層

百度這邊的開發者入口不只一個，一開始沒分清楚很容易在文件之間繞路。粗略可以分成兩層。

• AI 開放能力：文字識別、語音技術、人臉與影像、自然語言處理這類單點能力。輸入一張圖或一段音訊，回傳結構化結果。
• 大模型與智能體平台：百度千帆這一側，處理的是模型呼叫、微調、智能體編排這類需求。

如果你要做的是「把發票掃成欄位」或「把錄音轉成文字」，走第一層最省事。要做對話、生成、工具呼叫，才需要往第二層看。

授權：三個憑證與一顆 access_token

流程本身很短。在控制台建立一個應用，平台會分配 AppID、API Key、Secret Key 三個憑證。之後用後兩者去換 access_token。

官方採用的是 OAuth 2.0 的 client_credentials 模式：帶著 API Key 與 Secret Key 打授權端點，回傳的 JSON 裡就有 access_token 與有效期。

# structural sketch, check official docs for exact fields

POST https://aip.baidubce.com/oauth/2.0/token
    grant_type    = client_credentials
    client_id     = YOUR_API_KEY
    client_secret = YOUR_SECRET_KEY

# response
{
    "access_token" : "...",
    "expires_in"   : ...
}

拿到 token 之後，呼叫各項能力時把它帶上去即可。重點在於 token 要快取，不要每次呼叫都重換一次。

# structural sketch only

token = token_cache.get()          # refresh only when near expiry
if token is None:
    token = fetch_token(API_KEY, SECRET_KEY)
    token_cache.set(token, ttl=safe_ttl)

result = http_post(
    endpoint,                      # per ability, see official docs
    params  = {"access_token": token},
    headers = {"Content-Type": "application/x-www-form-urlencoded"},
    body    = payload,             # base64 image, audio, or text
)

三類介面的共同形狀

把 OCR、語音、NLP 三類擺在一起看，你會發現差別其實不大。授權共用、錯誤處理共用，真正不同的只有請求內容與回傳結構。

所以第一支應用的正確做法，是先把授權、重試、錯誤解析這層寫成共用模組，再讓三類能力共用它。不要每接一個能力就複製一份。

各能力的實際端點、參數名、輸入限制與回傳欄位都以官方文件為準，而且會隨版本調整，程式裡要留得住變化。

SDK、離線 SDK，還是自己包 HTTP

官方提供多語言 SDK，也針對部分能力提供可在裝置端執行的離線 SDK。三種做法各有適用情境。

• 官方 SDK：最快跑起來，適合驗證可行性與內部工具。缺點是升級節奏被綁住。
• 自己包 HTTP：多寫一點，但重試、逾時、日誌、快取全部握在自己手上。要上正式環境的服務，我會選這條。
• 離線 SDK：資料不能出機房、或現場網路不穩的情況才需要。要先確認授權方式與裝置需求。

成本控制：貴的通常不是單價

我不寫任何價格與配額數字，那些會變，而且各能力不同。真正能長期壓低帳單的是實作習慣，這幾條放到哪一家雲都成立。

1. 先在本地擋掉不必要的呼叫：空白圖、過小的檔案、明顯不合格式的輸入，根本不用送出去。
2. 把結果快取起來：同一張圖、同一段文字被重複處理，是帳單裡最常見的浪費。用內容雜湊當鍵。
3. 批次處理走批次介面：如果該能力有批次形式，一次送一筆是最貴的用法。
4. 壓縮與預處理放前面：影像先裁切與縮放、音訊先轉成規定的格式，既省流量也提高成功率。
5. 設上限與熔斷：單一使用者、單一時間窗的呼叫次數要有天花板，避免一支迴圈把整個月的預算燒光。
6. 記錄每一次呼叫：能力別、耗時、回傳碼、輸入大小。沒有這份紀錄，優化就只能靠猜。

2026 年的變化：從單點能力到模型服務

如果你是現在才開始接，值得知道生態已經往大模型那一側傾斜。百度千帆是模型服務與智能體開發平台，2026 年也在調整方案結構。

官方公告過 Coding Plan 於 2026 年 6 月底停止續費、後續由 Token Plan 個人版承接；企業版則主打相容 OpenAI 與 Anthropic 協議，並宣稱適配多種主流 AI 開發工具。

這對開發者其實是好消息：協議相容代表你寫的呼叫層可以在不同供應商之間搬，鎖定風險變小。但方案與模型清單變動很快，動手前一定要看當下的官方公告。