訪問和身份驗證

這裡提供完整的開發指南與最佳實踐，幫助您快速上手。

金鑰與 Header

金鑰端點以 X-API-Key Header 驗證；本章說明如何取得金鑰、如何帶入請求與安全建議。

取得 API 金鑰

登入開發者控制台。
前往「API 金鑰」頁面。
點擊「建立新金鑰」並為金鑰命名。
立即複製並妥善保存。金鑰只在建立當下顯示一次，離開頁面後無法再次取得。

金鑰範圍

金鑰綁定到建立它的帳號，可存取該帳號名下的字庫與用量配額。建立、列表、撤銷金鑰只在控制台 UI 進行，不對外提供管理 API。

在請求中帶入金鑰

請求路徑與認證對應

公開路徑: /translations/*
公開存取: 查詢翻譯支援的語言與模型清單；不需要 API Key，可直接呼叫。
公開路徑: /audio/*
公開存取: 查詢語音辨識支援的語言與模型清單；不需要 API Key，可直接呼叫。
私有路徑: /api/v1/*
需要 API Key: 在 X-API-Key header 帶入您的金鑰；放在 query string 或 body 會被視為缺失。

所有 /api/v1 路徑下的端點都需要在 HTTP Header 加上 X-API-Key。請勿放在 Query String 或 Body，會被視為缺失。

HTTP Header 範例

http

X-API-Key: [YOUR_API_KEY]

完整請求範例（curl）

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: [YOUR_API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello","target_language":"zh-TW"}'

未認證的回應

金鑰缺失、無效或撤銷時回 401，code = unauthorized。details 通常為空物件，不包含詳細的失敗原因（避免暴露金鑰是否存在）。

401 範例

json

{
  "error": {
    "code": "unauthorized",
    "message": "API key is missing or invalid.",
    "details": {},
    "request_id": "0af7651916cd43dd8448eb211c80319c"
  }
}

安全建議

金鑰保護

請勿將金鑰嵌入瀏覽器端、行動 App 二進位檔或公開 git 儲存庫。改由您自己的後端代理呼叫，並在後端讀取環境變數。

為不同應用建立不同金鑰，便於追蹤用量與限縮影響範圍。
定期輪替金鑰：建立新金鑰、切換流量、確認穩定後再撤銷舊金鑰。
懷疑外洩時，立即在控制台撤銷該金鑰並建立新金鑰。