인증

API 키

모든 /api/v1/*, /api/v1.1/* 요청은 Authorization 헤더에 API 키가 있어야 합니다.

Authorization: Bearer vuf_live_<keyid>.<secret>

키는 점(.)으로 구분된 두 부분으로 이루어집니다.

부분	역할
keyid	공개 식별자입니다. 서버에서 키를 찾는 데만 씁니다.
secret	비밀 부분입니다. 생성할 때 한 번만 보여 주며, 서버는 SHA-256 해시만 저장합니다.

vuf_live_ 접두사를 포함한 전체 문자열을 보내세요.

curl https://video.pyler.ai/api/v1/usage \
  -H "Authorization: Bearer $VUF_API_KEY"

키 발급

키는 대시보드의 API Keys 탭(video.pyler.ai/account/api-keys)에서 발급합니다.

경고

평문 secret은 생성할 때 한 번만 보여 주며, 이후에는 다시 확인할 수 없습니다. 페이지를 떠나기 전에 시크릿 관리 도구에 복사해 두세요. 잃어버렸다면 새 키를 만드세요.

팁

키를 소스 코드 저장소에 올리지 마세요. 환경 변수(이 문서의 예제는 VUF_API_KEY 사용)에 넣고 실행 시점에 읽으세요.

키는 조직에 속합니다

키는 개별 사용자가 아니라 조직을 식별합니다. 키로 만들거나 조회하는 모든 것(영상, 배치, 광고, 맞춤 요약, 심사 결과 등)은 해당 조직 범위로 한정되며, GET /api/v1/usage는 그 조직의 사용 한도를 보여 줍니다.

같은 키를 두 버전 루트 /api/v1, /api/v1.1에서 모두 쓸 수 있습니다.

401과 403

인증 실패에는 표준 오류 응답 형식을 씁니다.

상태	의미	조치
401	API 키가 없거나 유효하지 않습니다.	Authorization: Bearer ... 헤더가 있는지, 키가 온전한지 확인하세요. 헤더 누락이 가장 흔한 원인입니다.
403	공개 API 루트(/api/v1, /api/v1.1) 밖의 경로에 키를 썼습니다.	API 키는 공개 API에서만 동작합니다. 대시보드 경로는 브라우저 세션이 필요합니다.

인증 실패 응답에는 code 없이 detail만 담깁니다.

{ "detail": "authentication required" }

{ "detail": "invalid api key" }

{ "detail": "api key not permitted for this path" }

노트

대시보드에 로그인하면 쓸 수 있는 대화형 Swagger UI(video.pyler.ai/api-docs)의 오른쪽 위에 Authorize 버튼이 있습니다. 여기에 키를 한 번 넣으면 모든 "Try it out" 요청에 자동으로 실립니다. 이 사이트의 각 페이지에 있는 요청 패널도 같은 방식으로 동작하며, 탭을 닫으면 브라우저에 키를 남기지 않습니다.