認証と冪等性

ベアラー認証

キーの作成と失効は設定 → API キーで行います。秘密値が 表示されるのは一度だけです。標準のヘッダーで送信してください：

Authorization: Bearer sd_YOUR_KEY

受け付けるのは Authorization ヘッダーのみです。クエリ文字列での認証情報や X-API-Key には対応していません。キーが未指定・不正・期限切れ・失効済みの場合は 401 UNAUTHORIZED を返します。有効なキーでもエンドポイントのスコープがない場合は 403 FORBIDDEN を返します。

スコープ

アプリケーションごと・環境ごとに権限を絞った別のキーを使ってください。あるキーを 失効させても、そのアカウントで以前に作成されたジョブには影響しません。

冪等性

3 つの POST エンドポイントはいずれも、8〜255 文字の Idempotency-Key を必須と します。同じエンドポイントに同じキーと同一内容のリクエストを繰り返した場合、 クレジットを再度確保することなく元のジョブを返します。同じキーを異なる内容で 使い回すと 409 IDEMPOTENCY_CONFLICT を返します。

マルチパートのリクエストでは、元画像のバイト列も同一性の一部です。したがって、 キーを変えずにアップロード画像だけを差し替えると競合になります。

リクエスト ID

すべてのレスポンスに X-Request-Id が含まれます。エラー時のボディでは error.request_id として繰り返されます。リクエスト ID はアプリケーションの ログに保存しても安全です。