驗證方式
所有對外任務 API(/api/tasks/*)都必須在 request header 帶上：
X-Api-Key: sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
沒有帶這個 header 會直接收到 401 Unauthorized：
{ "message": "API key required." }
Key 類型
| 類型 | 字首 | 說明 |
|---|---|---|
paid |
sk-live- |
從你的付費積分餘額扣款,無使用期限 |
trial |
sk-test- |
綁定一筆試用積分額度(trial grant),使用該額度的剩餘額度,額度有到期日 |
Key 建立/重發當下會回傳一次明文,之後也可以隨時到 /app/api-keys 對應列表按「顯示」重新查看;列表 API 本身不會直接夾帶明文(只回傳 key_prefix)。
取得方式
Key 的建立/撤銷/重發都是帳號後台功能(登入 https://your-domain/app 後,/app/api-keys 頁面),不是對外 API 的一部分：
- 付費 Key:在
/app/api-keys的「付費」分頁直接建立,消耗帳號的付費積分餘額(GET /api/credits/balance可查詢,但此端點同樣需要登入態,不接受X-Api-Key)。 - 試用 Key:在「試用」分頁,選擇一筆你名下有效(未過期、有剩餘額度)的試用額度來綁定;同一筆額度同時只能有一支未撤銷的 Key。額度過期後無法再建立/重發該額度的 Key,已建立的 Key 也會在下一次驗證時被視為過期。
401 情境
| 情境 | message |
|---|---|
未帶 X-Api-Key header |
API key required. |
| Key 不存在或已撤銷 | Invalid API key. |
| 試用 Key 綁定的額度已過期 | This trial API key has expired.(回應另帶 active_key_prefixes 陣列,列出你名下其他仍有效的試用 Key 前綴,方便切換) |
頻率限制
超過限制回 429 Too Many Requests(見〈錯誤總表〉)。依 Key 類型套用不同上限：
| 類型 | 每分鐘 | 每日 |
|---|---|---|
paid |
300 | 100,000 |
trial |
20 | 1,000 |