API Key 생성(토큰)

MoleAPI에서는 API Key를 흔히 토큰이라고도 부릅니다. 이것은 API를 호출할 때 사용하는 신원 인증 정보이며, 일반적으로 sk-... 형태로 표시됩니다.

생성이 완료되면 Chatbox, NextChat, 몰입형 번역, OpenAI SDK 또는 사용자 정의 OpenAI 인터페이스를 지원하는 기타 도구에 입력하여 사용할 수 있습니다.

생성 전에 준비할 사항

시작하기 전에 아래 사항을 먼저 확인하는 것을 권장합니다.

1. 계정이 이미 등록되어 있으며 MoleAPI 콘솔에 로그인할 수 있어야 합니다.
2. 계정에 사용 가능한 잔액이 있거나, 최소한 신규 사용자에게 제공되는 테스트 Quota가 있어야 합니다.
3. 이 Key의 용도를 미리 정해 두는 것이 좋습니다. 예:
   • 일상 테스트
   • 로컬 개발
   • 특정 운영 프로젝트
   • 팀 내의 특정 독립 애플리케이션

1단계: KEY 관리 페이지로 이동

로그인 후, 콘솔 왼쪽 사이드바에서 KEY 관리 페이지로 이동합니다.

• 경로: 콘솔 → KEY 관리
• 바로가기 주소: https://home.moleapi.com/console/token

페이지에 들어간 후 상단의 토큰 추가를 클릭합니다.

2단계: 생성 폼 작성

클릭하면 새 토큰 생성 대화상자가 표시됩니다. 아래 이미지는 MoleAPI 콘솔의 실제 인터페이스를 기준으로 합니다.

지금은 일단 Key만 먼저 만들고 싶고, 모든 필드를 한 번에 이해하고 싶지 않다면, 성공 여부에 가장 큰 영향을 주는 다음 4가지만 우선 확인해도 됩니다.

• 이름: 나중에 용도를 쉽게 식별하기 위해 사용
• 토큰 그룹: 현재 Key가 어떤 모델 그룹을 사용할지 결정
• 만료 시간: 이 Key를 얼마나 오래 유지할지 결정
• 모델 제한: 확실하지 않다면 처음에는 제한하지 않아도 됨

아래에서 이 순서대로 하나씩 설명합니다.

1) 이름(필수)

이것은 해당 Key에 붙이는 메모용 이름으로, 용도를 구분하기 위한 것입니다.

권장 네이밍 방식:

• dev-local
• chatbox-test
• nextchat-prod
• openclaw-docs

이름만 봐도 의미를 알 수 있도록 지정하는 것을 권장합니다. 이렇게 하면 이후 사용 로그, Key 관리, Quota 제어에서도 더 쉽게 식별할 수 있습니다.

2) 토큰 그룹

여기서는 이 토큰이 어떤 그룹을 사용할지 결정합니다.

일반적으로 그룹은 다음에 영향을 줍니다.

• 사용 가능한 모델 범위
• 가격 정책
• Channel 안정성 또는 공급 출처

처음 생성하는 경우라면 우선 기본 그룹을 사용해도 됩니다. 플랫폼에 익숙해진 뒤 가격, 모델 가용성, 비즈니스 용도에 따라 더 적합한 그룹으로 전환하면 됩니다.

3) 만료 시간(필수)

MoleAPI는 만료 시간을 수동으로 선택할 수 있으며, 몇 가지 빠른 선택 버튼도 제공합니다.

• 만료 없음
• 1개월
• 1일
• 1시간

어떤 값을 선택하면 좋을지에 대한 가이드:

• 임시 테스트: 1일 또는 1시간 권장
• 로컬 개발: 1개월 권장
• 장기적이고 안정적인 서비스: 만료 없음을 선택할 수 있지만, Quota 및 보안 정책과 함께 사용하는 것이 좋습니다

초보자라면 우선 API 호출이 정상 동작하는지만 확인할 수 있도록 단기 Key를 먼저 만들고, 문제가 없으면 정식 Key를 추가로 생성하는 것을 권장합니다.

4) 생성 수량(필수)

기본값은 1이며, 토큰 1개만 생성한다는 의미입니다.

여러 환경이나 여러 구성원에게 독립적인 Key를 한 번에 배포해야 한다면 일괄 생성할 수 있습니다. 일괄 생성 시 시스템이 이름 뒤에 임의의 접미사를 추가해 구분을 돕습니다.

처음 사용하는 경우라면 1로 유지하면 됩니다.

5) Quota

여기서는 개별 토큰에 대해 사용할 수 있는 Quota 상한을 설정합니다.

다음 사항에 유의하세요.

• 이것은 토큰 자체의 Quota 상한이며, 계정 전체 잔액이 아닙니다.
• 여기서 높게 설정하더라도 실제 소비 가능 여부는 여전히 계정의 남은 잔액에 의해 제한됩니다.

이 Key를 소규모 테스트에만 사용하려면, 오용을 방지하기 위해 낮은 Quota를 설정하는 것이 좋습니다.

6) 무제한 Quota

기본적으로는 보통 활성화되어 있습니다.

활성화하면 이 토큰 자체에는 별도의 Quota 제한이 적용되지 않으며, 계정 잔액의 영향만 받습니다.

다음과 같이 이해하면 됩니다.

• 임시 테스트 Key: 무제한 Quota를 끄고 작은 Quota를 설정 가능
• 운영 서비스 Key: 활성화 여부는 리스크 제어 전략에 따라 결정

리스크 관리에 민감하다면 모든 Key에 무제한 Quota를 활성화하는 것은 권장하지 않습니다.

7) 모델 제한 목록

여기서는 이 Key가 어떤 모델을 호출할 수 있는지 제한할 수 있습니다.

제한하지 않으면 일반적으로 현재 그룹에서 허용된 모든 모델을 호출할 수 있다는 의미입니다.

권장 방식:

• 테스트 용도: 우선 제한하지 않아도 됨, 탐색에 유리
• 운영 프로젝트: 실제 업무에 필요한 모델만 허용
• 팀 협업: 시스템별로 Key를 분리하고, 모델 범위도 제한

이렇게 하면 다음과 같은 장점이 있습니다.

• 고가 모델의 오호출 방지
• 과도한 권한으로 인한 리스크 감소
• 로그 및 비용 원인 추적이 쉬워짐

8) IP 화이트리스트

여기에는 해당 Key에 대한 접근을 허용할 IP를 입력할 수 있으며, CIDR 표현식도 지원합니다.

입력하지 않으면 기본적으로 출발지 IP를 제한하지 않습니다.

IP 화이트리스트를 사용하는 것이 적합한 경우:

• 서버 측이 고정 서버에 배포되어 있는 경우
• 회사의 외부 IP가 고정되어 있는 경우
• 특정 운영 Key를 지정된 환경에서만 호출하도록 제한하고 싶은 경우

아직 로컬 디버깅 단계이고 고정된 외부 IP가 없다면, 우선 비워 두고 나중에 추가해도 됩니다.

3단계: 제출 후 API Key 복사

모든 내용을 확인한 뒤 오른쪽 아래의 제출을 클릭합니다.

생성이 완료되면 KEY 관리 목록에서 새로 생성된 토큰을 확인할 수 있습니다. 다음으로 즉시 아래 두 가지를 수행하세요.

1. 전체 API Key 복사
2. 다음과 같은 안전한 위치에 저장
   • 로컬 비밀번호 관리자
   • 환경 변수
   • 서버 비밀키 관리 시스템

초보자를 위한 권장 설정

MoleAPI를 우선 빠르게 실행해 보고 싶다면, 다음과 같이 생성하는 것을 권장합니다.

• 이름: dev-local
• 토큰 그룹: 기본 그룹
• 만료 시간: 1개월
• 생성 수량: 1
• Quota: 허용 가능한 테스트 Quota로 입력하거나, 우선 무제한 Quota 활성화
• 모델 제한: 우선 제한하지 않음
• IP 화이트리스트: 우선 비워 둠

이 설정이 가장 성공 가능성이 높으며, 이후 단계적으로 권한을 더 엄격하게 조정하면 됩니다.

생성 후 다음 단계

API Key를 받았다면, 실제 호출을 시작하려면 보통 다음 두 가지 정보가 더 필요합니다.

• Base URL: https://api.moleapi.com/v1
• API Key: 방금 생성한 sk-...

계속해서 다음 문서를 읽어보는 것을 권장합니다.

• API Key란 무엇인가요?
• Base URL이란 무엇인가요?
• Channel 그룹이란 무엇인가요?
• API Key 보안 설정

자주 묻는 질문

Key를 생성했는데도 호출에 실패하는 이유는 무엇인가요?

일반적인 원인은 다음과 같습니다.

• Base URL을 잘못 입력했거나 /v1을 빠뜨린 경우
• 모델명이 잘못된 경우
• 계정 잔액이 부족한 경우
• 토큰 그룹에서 해당 모델을 지원하지 않는 경우
• 토큰에 모델 제한 또는 IP 제한이 설정된 경우

하나의 계정으로 여러 API Key를 만들 수 있나요?

가능합니다. 모든 프로젝트가 하나의 Key를 공용으로 사용하는 것보다, 용도별로 여러 Key를 분리하는 것을 권장합니다.

테스트와 운영에서 하나의 Key를 같이 써도 되나요?

권장하지 않습니다. 다음과 같이 분리하는 것이 더 좋습니다.

• 테스트 Key 1개
• 운영 환경 Key 1개
• 필요 시 프로젝트 단위로 추가 분리

이렇게 하면 더 안전하고, 비용 제어와 문제 추적도 더 쉬워집니다.