Cursor 중계 API 연동 튜토리얼: 사용자 지정 Base URL 설정

1. Cursor란 무엇인가

Cursor는 VS Code를 기반으로 구축된 AI 네이티브 코드 에디터로, AI 채팅(Chat), 코드 생성(Composer/Chat) 및 지능형 자동 완성이 깊이 통합되어 있습니다. BYOK(Bring Your Own Key)를 지원하여, 공식 구독을 구매하고 싶지 않거나 특정 모델로 통합하여 사용하려는 경우 본인의 API Key로 자체 모델 엔드포인트에 연결할 수 있습니다.

중계 서비스를 연결하면 Cursor 공식 구독을 구매하지 않고도 사이트 내 sk- 키를 사용하여 토큰 단위로 과금하며 Claude / GPT / Gemini 모델을 이용할 수 있습니다.

2. 준비 작업

1. 극지(Jizhi) API 콘솔에 로그인하여 「API 키」에서 전용 sk-xxxxxx 키를 생성합니다.
2. 「모델 가격(模型定价)」에서 사용할 모델 슬러그(예: claude-sonnet-5, gpt-5.5, gemini-3.7-flash)를 확인합니다.
3. 게이트웨이 주소: https://www.relay-api.com을 확인합니다.

3. Cursor 설정 방법

Cursor → Settings → Models → API Keys를 엽니다(또는 설정에서 Models를 직접 검색):

1. 연결할 모델 제공업체를 선택합니다(OpenAI는 OpenAI 항목, Claude는 Anthropic 항목, Gemini는 Google Gemini 항목).
2. API Key를 입력합니다: sk-본인의키.
3. Override Base URL을 입력합니다: 선택한 제공업체에 따라 해당 게이트웨이 입구를 입력합니다.
   • Claude / Anthropic: https://www.relay-api.com
   • GPT / OpenAI: https://www.relay-api.com/v1
   • Gemini: https://www.relay-api.com/v1beta
4. Models 목록에 사용할 정확한 모델 ID를 추가합니다(모델 광장에서 슬러그를 복사하여 입력하고, 표시 이름은 사용하지 마세요).
5. Verify를 클릭하여 연결을 확인하고, 일반 채팅으로 짧은 텍스트를 보내 정상적으로 응답하는지 확인합니다.

4. 검수 및 문제 해결

현상	조치
401 / 403	키가 유효하지 않거나, 활성화되지 않았거나, 잔액이 부족합니다. sk-가 정확한지 확인하고 충전하세요.
404 / 모델 사용 불가	모델 슬러그가 플랫폼과 일치하지 않거나 해당 모델이 활성화되지 않았습니다. 모델 ID를 확인하세요.
Verify 통과 후 Agent 실패	/chat/completions 프로토콜 차이를 확인하고, 일반 채팅으로 먼저 기본 연결 상태를 검수하세요.
Tab 자동 완성 미작동	Tab Completion 등 전용 기능은 여전히 Cursor 내장 모델을 사용합니다. 이는 제품의 설계 범위이며 Base URL 설정 문제가 아닙니다.

보안 권장 사항: 키를 공개 저장소에 올리지 마세요. 프로젝트별로 별도의 키를 생성하고 잔액 및 사용량을 주기적으로 확인하는 것을 권장합니다.

Base URL 설명: 본 사이트는 /v1beta/models/...와 /v1beta/v1beta/models/...(및 /v1/...와 /v1/v1/...)를 모두 허용하므로, 클라이언트가 직접 /v1이나 /v1beta를 붙이는지 여부는 호출에 영향을 주지 않습니다. Base URL에 도메인 루트를 입력하거나 /v1beta가 포함된 주소를 입력해도 모두 작동합니다. 모델 ID는 콘솔 「토큰(令牌)」 페이지 우측 상단 「모델 ID」에서 조회 및 복사하십시오.