Sume API 헤더: 인증, 멱등성 키, If-Match, 요청 한도

Sume API를 호출할 때는 키를 Authorization: Bearer나 x-api-key 중 한쪽에만 담고(둘 다 보내면 안 됩니다), JSON 본문에는 Content-Type: application/json을, 생성 요청에는 Idempotency-Key를, Format 패키지 쓰기에는 If-Match를 보내세요. 모든 응답에는 x-sume-request-id가 실리고, API 응답에는 ratelimit-* 헤더가 포함될 수 있으며, 웹훅은 x-sume-webhook-* 헤더 세 개로 서명되어 도착합니다.

아래 헤더는 Sume 문서 인증, 오류와 비용 (영문), Format 패키지 편집하기, 웹훅 (영문)과 라이브 OpenAPI 레퍼런스에서 가져왔으며, 2026-09-27에 확인했습니다. 요청 한도 예산은 Sume API 오류와 요청 한도에서 설명합니다. 이 글은 헤더를 표 하나로 정리한 색인입니다.

Sume API는 어떤 헤더를 쓰나요?

각 행에는 해당 헤더를 자세히 설명하는 글을 링크했습니다. 표 아래의 요청은 생성 요청에 필요한 요청 헤더 세 개를 보냅니다. -D -를 붙이면 curl이 응답 헤더도 출력하며, 여기에는 x-sume-request-id와, 있다면 요청 한도 헤더도 포함됩니다.

curl -sS -D - -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-promo-v1" \
  -d '{"input": {"product_url": "https://example.com/p/8823"}}'

API 키는 어느 헤더에 담아야 하나요?

어느 쪽이든 일관되게 쓰되, 절대 둘 다 보내지는 마세요. 두 헤더를 모두 실은 요청은 Send only one API key credential. 메시지와 함께 401 unauthorized로 실패합니다. 이 오류를 일으키는 게이트웨이 함정은 Sume API 키 동작 방식에서 함께 설명합니다.

• TypeScript SDK는 x-api-key만 보내고, CLI도 기본값으로 x-api-key를 씁니다.
• 호스팅 MCP는 OAuth 대신 API 키로 연결할 때 두 헤더 중 어느 쪽이든 받습니다.
• 공개 경로 여섯 개는 키가 필요 없습니다. GET /v1/health, GET /v1/catalog, GET /v1/openapi.json, GET /v1/bgm/catalog, GET /v1/bgm/categories, POST /v1/bgm/pick입니다.
• 키가 곧 호출 주체입니다. Sume는 키에서 워크스페이스와 소유자를 해석하므로, 요청 본문에 workspace_id, owner_user_id, user_id를 넣지 마세요.
• 키는 서버에만 두세요. 프론트엔드 JavaScript나 모바일 앱에는 절대 넣지 마세요.

Idempotency-Key와 If-Match는 어떻게 다른가요?

Idempotency-Key는 생성 요청을 안전하게 재시도할 수 있게 합니다. 키와 본문이 같으면 원래 Job이나 실행이 돌아오고, 본문이 다르면 409 idempotency_conflict이며, Format 실행과 대량 실행 큐에서는 본문의 idempotency_key보다 헤더가 우선합니다. 키 설계는 AI 영상 API 멱등성 키에서 다룹니다.

반면 If-Match는 편집을 보호합니다. 이 헤더에는 Format의 package_sha를 담는데, 이 값은 불투명한 ETag가 아니라 40자 hex 문자열 그대로입니다. 값이 오래되면 409 format_package_sha_mismatch가 돌아오고, 현재 sha는 error.details.package_sha에 담깁니다. If-Match 낙관적 동시성을 참고하세요.

응답에는 무엇이 돌아오나요?

x-sume-request-id는 Sume 요청 ID로, 오류 본문의 error.request_id와 같은 값입니다. 생성 Job의 request_id와는 별개이므로, 지원팀에 문의할 때는 둘 다 알려 주세요. 이 값은 로그에 남기고, 같은 로그에서 API 키와 서명된 URL은 마스킹하세요.

요청 한도 헤더는 그 요청이 소진한 예산의 상태를 알려 주며, 그 예산은 읽기일 수도 쓰기일 수도 있습니다. 요금제별 예산은 Sume API 오류와 요청 한도에 나와 있습니다.

웹훅 헤더는 어떻게 검증하나요?

Sume는 타임스탬프 헤더의 값을 사용해, <timestamp>.<raw_body>에 대한 HMAC SHA-256으로 원본 본문에 서명합니다. 이 타임스탬프의 재전송 허용 시간은 오 분이 적당합니다.

• x-sume-webhook-signature를 쉼표로 나누고, sume-v1= 항목 중 하나라도 일치하면 전달을 수락하세요. 시크릿 교체 중에는 유효한 시크릿마다 항목이 하나씩 최신순으로 실리므로, 헤더 전체를 비교하면 검증에 실패합니다.
• x-sume-webhook-secret-fingerprint를 대시보드에서 시크릿 옆에 표시되는 지문과 비교하세요. 교체 중에는 이 헤더가 새 시크릿을 가리킵니다.
• Job 웹훅과 실행 웹훅은 이 방식과 서명 시크릿 하나를 공유하므로, 검증기 하나로 둘 다 처리할 수 있습니다.