이 시작 가이드에서는 API 키 발급부터 첫 API 호출까지의 과정을 안내합니다.

​
API 키

Clova Studio Gov API는 권한을 가진 사용자/애플리케이션만 호출할 수 있도록 식별 도구인 API 키를 테넌트별로 발급하고 있습니다. API 키는 API 호출 시 인증 정보로 전달하는 요청 헤더의 파라미터로 사용합니다. 따라서 Clova Studio Gov API를 사용하려면 우선 API 키를 발급받아야 합니다.

​
API 키 발급

API 키는 Clova Studio Gov 정보시스템 관리자 메뉴에서 발급할 수 있습니다.
API 키 발급 및 사용은 개발자 또는 관리자 권한이 필요합니다. 자세한 내용은 권한 관리를 참고하세요.
API 키 관리 화면
1

정보시스템 관리자 메뉴 접속

Clova Studio Gov 콘솔에 접속한 후, 좌측 사이드바에서 API 키 관리 메뉴를 클릭합니다.
2

새 API 키 생성

우측 상단의 + 새 API 키 생성 버튼을 클릭합니다.
3

API 키 확인 및 복사

“API 키가 생성되었습니다” 팝업이 나타나면:
  • 표시된 API 키를 복사 버튼을 클릭하여 복사합니다.
  • 완료 버튼을 클릭하여 팝업을 닫습니다.
4

API 키 안전하게 보관

복사한 API 키를 안전한 곳에 저장합니다.
중요:
  • 이 키는 한 번만 표시됩니다. 지금 복사하지 않으면 다시 볼 수 없습니다.
  • API 키를 분실한 경우, 기존 키를 삭제하고 새로운 키를 발급받아야 합니다.
  • API 키는 절대 공개 저장소나 클라이언트 코드에 포함하지 마세요.

​
API 키 삭제

API 키를 더 이상 사용하지 않거나 유출이 의심되는 경우 삭제할 수 있습니다.
1

API 키 관리 화면 접속

정보시스템 관리자 메뉴에서 API 키 관리를 클릭합니다.
2

삭제할 키 선택

삭제할 API 키의 우측에 있는 삭제 아이콘(🗑️)을 클릭합니다.
3

삭제 확인

확인 팝업이 나타나면 삭제 버튼을 클릭합니다.
4

새 API 키 발급 (필요시)

필요한 경우 위의 발급 절차에 따라 새 API 키를 발급받습니다.
삭제한 API 키는 즉시 무효화되어 더 이상 API 호출에 사용할 수 없습니다. 해당 키를 사용 중인 애플리케이션이 있다면 먼저 새 키로 교체한 후 삭제하세요.

​
공통 설정

Clova Studio Gov API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다.
API 키가 있는 경우, 바로 Clova Studio Gov API를 이용할 수 있습니다.

​
요청

공통 요청 형식을 설명합니다.

​
API URL

요청 API URL은 다음과 같습니다. 
https://api.clovastudio.go.kr/

​
요청 헤더

API 요청에는 다음 헤더가 필요합니다:
  • Authorization: Bearer <API-KEY> - (필수) 인증을 위한 API 키
  • Content-Type: application/json - JSON 요청 시
  • X-CSG-TENANT-ID: <tenant-id> - Clova Studio Gov 테넌트 ID (RAG42 API 사용시 필요)
자세한 내용은 요청 헤더 문서를 참조하세요.

​
응답

공통 응답 형식을 설명합니다.

​
응답 바디

  • statu (Object) : 응답 상태
  • status.code (String) : 응답 상태 코드
  • status.message (String) : 응답 메시지
  • result (Any) : 응답 결과

​
응답 예시

응답 예시는 다음과 같습니다.
  • 성공
{
  "status": {
    "code": "20000",
    "message": "OK"
  },
  "result": {}
}
  • 실패
{
"status": {
    "code": "50000",
    "message": "Internal Server Error"
    }
}
  • 실패 (OpenAI 호환 API)
{
"error": {
    "message": "Internal Server Error",
    "type": null,
    "param": null, //미지원
    "code": "50000"
    }
}

​
첫 API 호출

API 키를 발급받았다면 이제 첫 API 호출을 할 준비가 되었습니다. 다음은 간단한 텍스트 임베딩 API 호출 예제입니다.

​
예제: 텍스트 임베딩 생성

curl -X POST "https://api.clovastudio.go.kr/v1/text/embeddings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "텍스트 임베딩을 생성합니다"
  }'

​
다음 단계

인증

인증 방식과 보안 설정에 대해 자세히 알아보세요

API 엔드포인트

사용 가능한 모든 API 엔드포인트를 확인하세요

에러 처리

에러 코드와 처리 방법을 알아보세요

Chat Completions

대화형 AI API 사용법을 알아보세요