Skip to main content
Venice API 요청은 Bearer API 키로 인증됩니다. 이 가이드에서는 Venice 대시보드에서 키를 생성하고, 안전하게 보관하며, 정상 작동 여부를 확인하는 방법을 설명합니다.
지갑으로 자체 키를 발급해야 하는 자율 에이전트를 구축하는 경우에는 자율 에이전트 API 키 생성 가이드를 대신 사용하십시오.

​
시작하기 전에

  • Venice 계정에 로그인합니다.
  • 유료 엔드포인트를 호출하기 전에 계정에 사용 가능한 잔액이 있는지 확인하십시오. 계정에 자금을 충전하기 전에도 키를 생성할 수 있지만, 계정이 DIEM, 번들 크레딧 또는 USD를 사용할 수 있을 때까지 모델 요청은 성공하지 않습니다.
1

API 설정 열기

https://venice.ai/settings/api을 방문합니다. Venice 앱의 설정에서 API를 선택하여 이 페이지를 열 수도 있습니다.API 설정 대시보드에는 잔액, API 등급, 사용량 및 기존 API 키가 표시됩니다.
2

새 키 시작하기

Generate New API Key를 선택한 다음, 키를 구성합니다:
  • Description: 이 키를 사용할 앱, 환경 또는 통합을 식별할 수 있는 짧은 이름을 사용하십시오.
  • API Key Type: 일반적인 모델 요청에는 Inference Only를 사용합니다. 키가 프로그래밍 방식으로 API 키를 관리해야 하는 경우에만 Admin을 사용하십시오.
  • Expires at: 선택적으로 만료 날짜를 설정합니다. 비워두면 키는 자동으로 만료되지 않습니다.
  • Epoch Consumption Limits: 선택적으로 이 키가 24시간 epoch 동안 사용할 수 있는 DIEM 또는 USD 금액을 제한합니다. 비워두면 키는 계정 한도 내에서 계정의 사용 가능한 잔액을 사용할 수 있습니다.
3

키 생성 및 복사

Generate를 클릭합니다. Venice는 전체 API 키를 한 번만 표시합니다.
키를 즉시 복사하여 안전한 위치에 보관하십시오. 대화상자를 닫은 후에는 Venice가 키 설명과 마지막 문자와 같은 식별용 메타데이터만 표시합니다. 비밀 값을 분실한 경우 해당 키를 삭제하고 새로 생성하십시오.
키는 발급된 그대로 붙여넣으십시오. 텍스트를 직접 드래그하여 선택하지 말고 대화상자의 복사 버튼을 사용하면 첫 문자나 마지막 문자가 잘리거나 끝에 줄바꿈이 포함되는 것을 방지할 수 있습니다. 도구의 입력 필드에 키를 입력해야 하는 경우 키만 입력하십시오. Bearer 접두사, 앞뒤 따옴표, 앞뒤 공백을 포함하지 마십시오. 대화상자를 닫은 후에는 대시보드에 마지막 몇 문자만 표시되므로, 분실한 키를 마스킹된 값을 다시 입력하는 방식으로 복원하려고 시도하지 마십시오.키를 로컬 환경 또는 시크릿 매니저에 추가합니다:
4

키 확인하기

인증이 정상적으로 작동하는지 확인하기 위해 위험이 낮은 요청을 보냅니다. Get API Key Rate Limits and Balances는 비용이 들지 않으며 두 가지 키 유형을 모두 허용합니다. GET /models는 키 유무와 관계없이 모델 카탈로그를 반환하므로 키가 잘못되었더라도 성공합니다. 따라서 GET /models 대신 이 엔드포인트를 사용하십시오:
성공적인 응답은 API 티어, 잔액 및 속도 제한을 반환하며, data.accessPermitted는 해당 키가 추론 엔드포인트를 사용할 수 있는지 여부를 알려줍니다.AUTHENTICATION_FAILED와 함께 401이 반환되면 키 자체가 거부된 것입니다. 저장된 값을 출력하여 대시보드에 표시된 마지막 문자와 비교하십시오. 일반적인 원인은 키의 일부만 복사된 경우, Bearer 접두사나 따옴표가 값 자체에 포함된 경우, 또는 앞뒤에 불필요한 공백이나 줄바꿈이 있는 경우입니다. 또한 헤더가 Bearer <api-key> 형식이며 두 부분 사이에 정확히 한 칸의 공백이 있는지 확인하십시오.
Venice 앱에서 API 키를 생성할 때 USD 지출을 비활성화하면 해당 API 키의 USD 지출 한도가 0으로 설정됩니다. 계정에 USD 잔액이 있더라도, 사용 가능한 DIEM 또는 번들 크레딧이 요청 비용을 감당할 수 없는 경우 API 호출이 잔액 부족 오류로 실패할 수 있습니다.

​
지출 한도 오류 해결하기

키별 지출 한도는 계정 잔액과는 별개입니다. 계정에 아직 충전된 USD 크레딧, DIEM 또는 번들 크레딧이 남아 있어도 특정 키는 지출이 차단될 수 있습니다. 요청이 다음 코드 중 하나와 함께 402를 반환하는 경우, 원인은 계정 잔액이 아니라 해당 키 자체의 한도입니다:
  • API_KEY_USD_SPEND_LIMIT_EXCEEDED — 키의 USD 지출 한도가 0으로 설정되어 있거나(키 생성 시 USD 지출이 비활성화됨) 현재 epoch가 USD 상한에 도달했습니다.
  • API_KEY_DIEM_SPEND_LIMIT_EXCEEDED — 키가 현재 24시간 epoch의 DIEM 상한에 도달했습니다.
키의 현재 상태를 확인하려면 Get API Key Rate Limits and Balances를 호출하고 data.accessPermitted, data.balances 및 키별 소비 한도를 확인하십시오. 오류를 해결하려면 venice.ai/settings/api에서 키의 Epoch Consumption Limits를 상향 조정하거나 제거하거나, 새로운 consumptionLimits로 Update API Key를 호출하십시오. 계정 전체 잔액(USD, DIEM 및 번들 크레딧)은 독립적인 결제 수단이며 사용 가능한 대로 자동으로 소비됩니다. 요청 시점에 어느 것을 사용할지 선택할 필요가 없습니다. 청구 관련 응답의 전체 목록은 Error Codes를 참조하십시오.

​
모범 사례

  • 개발, 스테이징, 프로덕션 환경별로 별도의 키를 생성하십시오.
  • 모델 엔드포인트만 호출하는 애플리케이션에는 Inference Only 키를 사용하는 것이 좋습니다.
  • Admin 키는 최소한으로 사용하고, 범위를 엄격히 제한하며, 신뢰할 수 있는 서버 측 환경에만 보관하십시오.
  • API 키를 소스 컨트롤에 커밋하거나 클라이언트 측 코드에 노출하지 마십시오.
  • 임시, 공유 또는 위험도가 높은 환경에서 사용되는 키에는 만료 날짜와 소비 한도를 설정하십시오.
  • 사용하지 않는 키는 삭제하고, 노출되었을 가능성이 있는 키는 교체하십시오.

​
프로그래밍 방식 키 관리

Admin 키는 API 레퍼런스 엔드포인트를 통해 API 키를 관리할 수 있습니다:

API 키 생성

기존 admin 키에서 새 대시보드 형식의 API 키를 생성합니다.

API 키 목록 조회

활성 키와 해당 메타데이터를 확인합니다.

API 키 업데이트

키 설명, 만료 날짜 또는 소비 한도를 업데이트합니다.

API 키 삭제

더 이상 필요하지 않은 키를 폐기합니다.