인증

생성·조회·과금을 수행하는 모든 API 호출은 Authorization 헤더에 API 키를 보냅니다. 평가용 공개 모델 카탈로그만 예외로 키가 필요하지 않습니다.

Authorization: Bearer sk-spicy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

네이티브 API(/api/v1/*)는 Bearer 키만 받습니다. 쿠키나 쿼리 매개변수는 받지 않습니다.

텍스트·영상 호환 엔드포인트(/v1, /v1beta)는 같은 키를 사용하며 Anthropic SDK의 x-api-key와 Google GenAI SDK의 x-goog-api-key 헤더도 받습니다. 따라서 공식 SDK에서 기본 URL만 바꿔 사용할 수 있습니다. 텍스트와 스트리밍을 참고하세요. 이 두 헤더는 /api/v1에서는 효력이 없으며 어떤 엔드포인트도 URL 쿼리 문자열의 키는 허용하지 않습니다.

API 키와 콘솔은 별개입니다

API 키는 /api/v1, /v1, /v1beta에서만 받습니다. 웹 콘솔은 별도 브라우저 세션을 사용합니다. 콘솔 로그인을 API 키로 쓸 수 없으며 유출된 API 키로 콘솔에 로그인할 수도 없습니다. 잘못된 종류의 인증 정보를 보내면 권한 오류가 아니라 항상 401입니다.

키 형식

고정 접두사 sk-spicy- 뒤에 소문자 16진수 48자가 이어집니다.

접두사는 의도된 설계입니다. 다른 사람이 잔액을 쓴 뒤 알아차리기보다 스캔을 통해 알림을 받는 편이 낫습니다.

키 생성

1. 콘솔 → API 키에서 키 생성을 누르세요.
2. 사용할 서비스 이름을 붙이세요(production backend, staging worker). 해지할 때 알아볼 수 있어야 합니다.
3. 선택적으로 고급에서 지출 한도, 허용 모델, IP 허용 목록과 만료일을 설정하세요. 모두 나중에 바꿀 수 있습니다.
4. 키를 복사하거나 파일로 저장하고 보관했음을 확인하세요. 대화상자가 닫히면 다시 표시할 수 없습니다.

팀 소유자·관리자·개발자 역할이 키를 생성할 수 있습니다. 키는 콘솔 왼쪽 위에서 선택한 팀에 소속되며 사용량과 한도도 해당 팀에 집계됩니다. 팀마다 활성 키 최대 50개를 보유할 수 있습니다. 유료 작업을 수행하려면 이메일 인증과 잔액도 필요합니다. 계정 설정을 참고하세요.

키 보관 위치

• 컴퓨터에서 테스트: 터미널에서 export SPICY_API_KEY="…"를 설정하세요(창을 닫을 때까지 유효). 또는 코드가 읽는 .env 파일을 사용하세요. 첫 커밋 전에 .env를 .gitignore에 추가하세요.
• 서버·호스팅 플랫폼: 비밀 정보 또는 환경 변수 설정을 사용하고 코드에서 환경의 SPICY_API_KEY를 읽으세요.
• 소스 코드, 채팅, 스크린샷, 지원 문의 또는 AI 도우미 프롬프트에 키를 붙여 넣지 마세요.

클라이언트에 키를 배포하지 마세요

모바일 바이너리, 데스크톱 클라이언트, 공개 노트북, CI 로그와 지원 문의에 붙여 넣는 curl -v 출력에도 같은 원칙이 적용됩니다.

자신의 브라우저에서 자신만 쓰는 도구는 다릅니다. API는 브라우저 호출을 허용하므로 자체 키를 입력하는 SillyTavern 확장이나 롤플레잉 앱은 직접 호출할 수 있습니다. 위 규칙은 다른 사람이 불러오는 제품에 키를 넣는 경우입니다. 이런 개인 도구마다 일 지출 한도가 있는 별도 키를 부여하면 소비를 확인하고 각각 해지할 수 있습니다.

키별 제한

키 생성 시나 이후 콘솔에서 설정하며 서버에서 적용합니다.

각 키 카드에서 현재 한도를 확인하고 언제든 변경할 수 있습니다.

한도는 이미 쓴 금액과 진행 중 작업의 선점 금액을 함께 계산하므로 작업이 끝나기 전에 도달할 수 있습니다. msg는 도달한 한도를 알려 줍니다. 40202의 msg가 플랫폼 할당량을 언급하면 키 한도가 아닙니다. 새 키를 만들어도 해결되지 않으므로 나중에 재시도하세요.

IP 허용 목록은 마지막 프록시 주소가 아니라 엣지 네트워크가 보는 실제 공개 주소와 비교합니다. 송신 주소는 서버 요청이 나오는 공인 IP입니다. 보통 호스팅 플랫폼의 네트워크 설정에서 확인할 수 있으며 자체 컴퓨터에서는 curl https://ifconfig.me로 확인합니다.

작업은 생성한 키에 귀속됩니다

API에서는 작업을 생성한 키만 해당 작업에 접근할 수 있습니다. 같은 팀이라도 다른 키를 사용하면 다음과 같습니다.

두 가지는 키에 묶이지 않습니다. 작업 webhook은 생성한 키를 해지한 뒤에도 전달됩니다. 또한 어떤 키로 만들었든 팀의 모든 작업은 콘솔 → 로그에 표시되며 상세에 사용한 키가 나옵니다.

키 교체

• 운영·스테이징·로컬 환경마다 키 하나를 사용하면 다른 환경에 영향 없이 해지할 수 있습니다.
• 계획된 교체: 새 키를 만들고 새 작업만 새 키로 보내세요. 이전 키의 모든 작업이 종료 상태(늦어도 해당 작업의 deadlineAt)에 도달하고 결과를 수집한 뒤 이전 키를 해지하세요. 이전 키를 신뢰할 수 있을 때만 이 순서를 사용합니다.
• 해지는 즉시 적용되며 되돌릴 수 없습니다. 캐시 만료를 기다릴 필요도 없으며 다시 활성화할 수도 없습니다. 새 키를 생성해야 합니다.

유출 후 대응

예상하지 못한 지출이 있다면 작업 ID 또는 request_id를 포함하여 콘솔 → 지원으로 문의하세요.

인증 실패 응답

{
  "code": 401,
  "msg": "Credentials are invalid or expired",
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

HTTP 상태도 401입니다. 모든 인증 실패는 code: 401을 반환하며 msg로 종류를 설명합니다.

문구가 아니라 code로 분기하세요. 문구는 바뀔 수 있고 오류 언어를 따릅니다. 구분 방법은 오류에서 자세히 설명합니다.

이메일 미인증·계정 정지 등 계정 자체가 API를 호출할 수 없다면 403을 받습니다. 키를 바꿔도 해결되지 않습니다.