CLOVA Studio API 키를 안전하게 발급하고 첫 호출하는 법

|작성자: QUASA 편집팀|6 분 소요
CLOVA Studio API 키를 안전하게 발급하고 첫 호출하는 법

CLOVA Studio의 첫 API 호출에는 네이버 클라우드 플랫폼 콘솔에서 발급한 테스트 API 키를 사용하면 된다. CLOVA Studio 개요에 안내된 대로 키를 발급해 안전하게 복사한 뒤, 요청의 Authorization 헤더에 Bearer와 공백, 키값을 차례로 넣는다. 이 글의 예제는 일반 네이버 클라우드 플랫폼 환경에서 실행하는 Bash 명령이다.

키를 저장소나 호출 명령에 직접 적지 않도록 터미널 환경변수에 잠시 보관하고, 새 호출 주소로 대화 생성 요청을 보낸다. 예전 API Gateway 주소와 구 버전 인증 헤더가 검색 결과에 함께 남아 있으므로, 새 키를 사용한다면 주소와 헤더를 모두 현재 방식에 맞춰야 한다. 호출이 실패했을 때는 응답 코드로 원인을 좁히고, 키 노출이 의심되면 콘솔에서 기존 키를 삭제한 후 새 키로 교체한다.

콘솔에서 테스트 API 키 발급하기

CLOVA Studio 테스트 API 키를 발급할 때 값을 복사해야 하는 절차

네이버 클라우드 플랫폼 콘솔에 로그인해 화면 오른쪽 위에서 이용 중인 리전과 플랫폼을 선택하고 적용한다. 이어 Menu → All Services → AI Services → CLOVA Studio → API 키로 이동한다. 콘솔에서 고른 환경을 확인한 뒤 발급 화면으로 들어가야 뒤에서 사용할 호출 주소와 키의 환경을 혼동하지 않는다.

  1. 서비스 앱을 통하지 않고 첫 요청을 시험한다면 ‘테스트’ 탭에서 ‘테스트 API 키 발급’을 선택한다.
  2. 등록을 마친 서비스 앱에서 사용할 키가 필요하다면 ‘서비스’ 탭의 ‘서비스 API 키 발급’을 선택한다. 서비스 앱 이용에는 별도의 신청 절차가 따른다.
  3. API 키 복사 창에서 ‘발급’을 누르고 표시된 값을 복사한 다음 ‘완료’를 누른다. 복사한 값은 이 글의 터미널 입력 단계에 사용한다.

발급 창을 닫으면 새 키의 값을 다시 확인할 수 없다. 창을 닫기 전에 복사가 끝났는지 확인하고, 복사에 실패했다면 새 키를 발급한다. 키를 채팅방, 이슈 본문 또는 저장소 파일에 붙여 넣어 임시 보관하는 방식은 피한다. 이 값은 요청을 인증하는 자격 증명이므로 공유 범위가 넓어지면 제삼자가 사용할 위험도 커진다.

테스트 키는 서비스 앱을 제외한 CLOVA Studio API 호출에 쓰이고, 서비스 키는 등록이 완료된 서비스 앱 호출에 쓰인다. 따라서 아래 명령으로 테스트 키가 동작해도 서비스 앱 등록과 신청이 끝났다는 뜻은 아니다. 배포 목적이 서비스 앱 연동이라면 해당 앱의 등록 상태와 서비스 키 사용 조건을 따로 확인해야 한다.

새 Bearer 인증과 구 버전 주소 구분하기

현재 발급 방식의 키는 Authorization 헤더에 ‘Bearer 키값’ 형태로 전달한다. Bearer와 키값 사이에는 공백이 필요하다. 구 버전 예제의 X-NCP-CLOVASTUDIO-API-KEY와 X-NCP-APIGW-API-KEY는 이전 키와 API Gateway 키를 함께 사용하던 흐름에 속한다. 새 키를 발급해 놓고 그 예제의 헤더 이름만 복사하면 요청의 인증 방식이 맞지 않는다.

일반 네이버 클라우드 플랫폼 환경의 새 API 기본 주소는 https://clovastudio.stream.ntruss.com/이다. 문서에 남아 있는 https://clovastudio.apigw.ntruss.com/ 주소는 지원 중단이 예정돼 있으며, 새 API 키를 통한 인증과 생성 토큰 단위의 스트리밍 응답을 지원하지 않는다. 이미 구 주소를 쓰는 코드라면 키만 바꿀 일이 아니라 요청 주소와 헤더도 함께 점검해야 한다.

첫 호출에는 별도의 Accept 헤더를 넣지 않아도 된다. 이 경우 응답을 기본 JSON 형식으로 받으며, 생성되는 내용을 스트림으로 받고 싶을 때 Accept: text/event-stream을 지정한다. 스트림 응답은 이벤트가 이어서 전달되므로 일반 JSON 응답을 한 번에 읽는 코드와 처리 방법이 다르다. 먼저 기본 응답으로 인증과 경로를 확인한 뒤 필요한 경우에 스트림을 적용하는 편이 이해하기 쉽다.

이 예제의 도메인은 일반 환경을 위한 것이다. 공공기관용 환경처럼 별도 콘솔을 이용한다면 일반 환경의 주소를 그대로 가져다 쓰지 말고 그 환경에 안내된 API 주소를 사용해야 한다. 키를 발급받은 환경과 호출할 환경을 맞추는 것이 인증 오류를 살필 때도 출발점이다.

키를 Bash 환경변수에 임시 보관하기

발급 창에서 복사한 키를 curl 명령 안에 직접 입력하면 명령 기록이나 공유한 예제에 원문이 남을 수 있다. Bash 터미널에서는 다음 명령을 먼저 실행한다. 입력 대기 상태가 되면 키를 붙여 넣고 Enter를 누른다. read의 -s 옵션 때문에 붙여 넣은 값은 화면에 표시되지 않는다.

read -r -s CLOVA_STUDIO_API_KEY; export CLOVA_STUDIO_API_KEY; printf '\n'

이 명령은 현재 셸에서 입력받은 값을 CLOVA_STUDIO_API_KEY 환경변수로 내보낸다. 이어서 실행할 curl은 변수에서 값을 읽으므로, 복사해 공유하는 요청 명령에는 키 원문이 들어가지 않는다. 다만 환경변수는 그 셸에서 시작한 프로그램에도 전달된다. 공용 계정에서 오래 켜 두거나 영구 보관하는 수단으로 생각하지 말고, 실습을 마치면 unset CLOVA_STUDIO_API_KEY로 현재 셸의 값을 지운다.

다른 터미널 창을 열면 앞서 입력한 셸 변수는 그 창에 자동으로 생기지 않는다. 인증 오류가 나면 요청을 실행한 터미널에서 키를 입력했는지 먼저 살핀다. 붙여 넣을 때 키 앞뒤의 공백까지 복사하지 않았는지도 확인한다. Bearer 다음의 공백은 헤더 형식에 필요하지만, 키값에 덧붙은 공백은 인증에 쓰일 값 자체를 바꾼다.

애플리케이션을 배포할 때는 실행 플랫폼의 비밀값 관리 기능에 키를 등록하고 실행 시 읽도록 설정한다. 공유 셸 설정 파일에 실제 키를 넣어 두면 파일을 복제하거나 저장소에 반영하는 과정에서 값이 퍼질 수 있다. 로컬의 임시 환경변수와 배포 환경의 비밀값은 보관 장소가 다르므로, 나중에 키를 교체할 때도 각각의 설정을 확인해야 한다.

curl로 첫 대화 요청 보내기

Chat Completions v3 명세는 POST /v3/chat-completions/{modelName} 경로와 HCX-DASH-002 모델, 필수 messages 필드를 안내한다. 다음은 사용자 메시지로 짧은 한국어 인사말을 요청하는 예제다. maxTokens의 64는 이 예제에서 지정한 최대 생성 토큰 수이며, 실제 답변의 길이나 문구를 보장하는 값은 아니다.

curl -sS -i -X POST 'https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-DASH-002' -H "Authorization: Bearer ${CLOVA_STUDIO_API_KEY}" -H 'Content-Type: application/json' --data '{"messages":[{"role":"user","content":"안녕하세요. 한 문장으로 인사해 주세요."}],"maxTokens":64}'

Authorization 헤더를 감싼 큰따옴표는 그대로 둔다. Bash가 ${CLOVA_STUDIO_API_KEY}를 실제 값으로 바꾸려면 변수 부분이 큰따옴표 안에 있어야 한다. 이 헤더를 작은따옴표로 감싸면 변수 이름이 문자 그대로 전송된다. 반대로 JSON 본문은 작은따옴표로 감싸 내부의 큰따옴표를 셸이 해석하지 않게 했다.

curl의 -i 옵션은 HTTP 응답 헤더도 함께 보여 준다. 성공한 요청이라면 본문에서 status.code와 result를 확인하고, 생성된 문장은 result.message.content에서 찾는다. 응답 문구가 예제의 지시와 정확히 같은지보다 인증이 통과했는지, 기대한 모델 경로에서 결과가 왔는지가 첫 확인 대상이다. 오류가 돌아오면 HTTP 상태와 본문의 status.code를 함께 기록해 원인을 구분한다.

처음부터 스트리밍을 사용할 필요는 없다. 실시간으로 문장을 표시해야 하는 애플리케이션이라면 확인된 요청에 Accept: text/event-stream을 추가하고 이벤트별 응답을 처리한다. 요청 추적이 필요한 경우에는 선택 항목인 X-NCP-CLOVASTUDIO-REQUEST-ID를 붙일 수 있다. 이 두 헤더는 첫 JSON 응답을 받기 위한 필수 항목이 아니다.

오류를 좁히고 노출된 키 교체하기

노출이 의심된 CLOVA Studio API 키를 삭제하고 새 키로 교체하는 과정

CLOVA Studio 오류 안내는 40100을 인증 실패, 40104를 유효하지 않은 키, 40170을 서비스 이용 신청 이력 없음, 40300을 권한 부족, 40080을 찾을 수 없는 모델로 구분한다. 키를 무작정 다시 발급하기 전에 응답 본문의 코드를 읽으면 어느 설정을 확인할지 정할 수 있다.

40100 또는 40104가 나타나면 먼저 Authorization 헤더의 Bearer 형식, 환경변수에 입력한 값, 새 API 주소를 차례로 확인한다. 40170이라면 콘솔에서 CLOVA Studio 이용 신청 상태를 살핀다. 40300은 요청 기능에 대한 사용 권한을 확인할 신호이고, 40080은 경로에 넣은 모델 이름을 다시 볼 신호다. 요청 본문의 형식이 잘못됐다면 인증과 별개로 메시지 필드와 JSON 구문을 점검해야 한다.

키가 저장소나 로그, 채팅방에 노출됐거나 도용이 의심되면 정상 호출이 되더라도 그 키를 계속 사용하지 않는다. 콘솔의 CLOVA Studio → API 키에서 해당 키가 있는 탭을 열고, 키의 더보기 메뉴에서 삭제를 선택한다. 이어 새 키를 발급해 필요한 실행 환경의 비밀값을 교체한다. 삭제한 키는 더 이상 API 호출에 사용할 수 없으므로, 사용 중인 프로그램의 교체 준비도 함께 해야 한다.

같은 키를 개발 터미널과 배포 설정에서 사용했다면 어느 곳에 값이 남아 있는지 확인한다. 한쪽에만 새 키를 넣으면 다른 쪽의 요청은 삭제된 키로 계속 실패한다. 노출된 값을 남겨 둔 채 새 키만 추가하는 것도 해결이 되지 않는다. 기존 키의 삭제와 실제 호출 환경의 새 키 적용까지 마쳐야 자격 증명 교체가 끝난다.

함께 읽기:

공유:

뉴스레터 구독

최신 Web3, AI, 암호화폐 뉴스를 이메일로 받아보세요.

0