API 文件API 文件
驗證與冪等性
API 金鑰、權限範圍、請求 ID 與安全重試
Bearer 驗證
在設定 → API 金鑰建立或撤銷金鑰。明文只會顯示一次， 請透過標準標頭傳送：
Authorization: Bearer sd_YOUR_KEY只接受 Authorization 標頭。不支援以查詢字串傳遞憑證，也不支援 X-API-Key。
金鑰缺少、無效、過期或已撤銷時回傳 401 UNAUTHORIZED。金鑰有效但缺少該端點所需
權限範圍時回傳 403 FORBIDDEN。
權限範圍
| 權限範圍 | 允許的操作 |
|---|---|
images:generate | 建立生成任務 |
images:edit | 建立編輯任務 |
images:convert | 建立轉換任務 |
jobs:read | 讀取同一帳號的任務 |
credits:read | 讀取目前點數餘額 |
請為每個應用程式與環境使用各自受限的金鑰。撤銷某一把金鑰，不會影響該帳號先前 已建立的任務。
冪等性
三個 POST 端點都必須帶上長度介於 8 到 255 字元的 Idempotency-Key。以相同金鑰
和相同正規化內容重複呼叫同一端點時，會回傳原本的任務，而不會再次預留點數。若以
相同金鑰搭配不同內容，則回傳 409 IDEMPOTENCY_CONFLICT。
對於 multipart 請求，來源影像的位元組也是識別依據的一部分。因此保留金鑰卻更換 上傳影像，會被視為衝突。
請求 ID
每個回應都包含 X-Request-Id。錯誤回應的主體會以 error.request_id 再次帶出。
請求 ID 可以安全地寫進應用程式日誌。