API 문서API 문서
인증과 멱등성
API 키, 범위, 요청 ID, 안전한 재시도
Bearer 인증
키 생성과 폐기는 설정 → API 키에서 합니다. 비밀값은 단 한 번만 표시됩니다. 표준 헤더로 보내세요:
Authorization: Bearer sd_YOUR_KEYAuthorization 헤더만 받습니다. 쿼리 문자열로 전달하는 자격 증명과 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는 애플리케이션 로그에 저장해도
안전합니다.