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

​
API 키

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

​
API 키 발급

API 키는 CLOVA Studio에서 발급할 수 있습니다. 발급 방법은 다음과 같습니다.
  1. Clova Studio 콘솔에 접속해 주십시오.
  2. 테넌트를 선택하세요.
  3. 화면 좌측에서 API 키 메뉴를 클릭해 주십시오.
  4. API 키 화면이 나타나면 발급할 API 키 탭 메뉴를 클릭한 다음 발급 버튼을 클릭해 주십시오.
  • 등록 완료된 서비스 앱의 CLOVA Studio API 호출 시 이용 가능
  • 테넌트별로 최대 10개까지 생성 가능
  1. API 키 복사 팝업 창이 나타나면 [발급] 버튼을 클릭해 주십시오.
  2. [복사] 버튼을 클릭한 다음 [완료] 버튼을 클릭해 주십시오.
API 키 복사 팝업 창을 닫은 후에는 발급한 API 키 확인이 불가능합니다. 따라서 발급 시점에 반드시 별도의 안전한 공간에 보관하여 주십시오.

​
API 보안 설정

API 키가 제3자에게 유출되는 경우, CLOVA Studio 리소스를 임의로 이용하는 등 보안 문제가 발생할 수 있으므로 적절한 사전 대비와 대응이 필요합니다.

​
API 키 삭제 및 재발급

API 키를 사용하지 않거나 제3자의 도용이 의심된다면 발급한 API 키를 삭제한 후 다시 발급해야 합니다. 삭제 및 재발급 방법은 다음과 같습니다.
  1. Clova Studio 콘솔 화면 좌측에서 API 키 메뉴를 클릭해 주십시오.
  2. API 키 화면이 나타나면 삭제할 API 키가 있는 탭 메뉴를 클릭해 주십시오.
  3. 삭제할 API 키의 more 아이콘을 클릭한 다음 삭제 메뉴를 클릭해 주십시오.
  4. API 키 삭제 팝업 창이 나타나면 [삭제] 버튼을 클릭해 주십시오.
  5. 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 사용법을 알아보세요