자체 모델 키 연결하기
모델 제공업체 또는 게이트웨이의 키를 연결하세요. 연결하려면 제공업체, 엔드포인트, 모델 ID 및 계정 권한이 서로 일치해야 합니다.
연결 정보 준비하기
호출하려는 서비스의 API 키, 해당 서비스의 API 기본 URL, 사용 가능한 모델 ID, 호환되는 프로토콜 또는 프리셋이 필요합니다. 일반 사용자용 채팅 웹사이트의 계정만으로는 API 액세스 권한이나 API 크레딧이 제공되지 않습니다.
Free를 포함한 모든 요금제에서 BYOK를 지원합니다. 제공업체 키를 사용하면 OpenDesign 잔액이 아니라 해당 제공업체의 청구 및 사용 한도가 적용됩니다.
제공업체 추가하기
- Settings → Models & providers → API providers를 엽니다.
- 키를 발급한 서비스의 프리셋을 선택합니다. Custom provider를 사용하는 경우 해당 서비스 문서에 명시된 프로토콜과 일치시킵니다.
- API Key에는 비밀 키만 붙여 넣습니다. Bearer, 따옴표 또는 JSON 구성 래퍼를 추가하지 마세요.
- Base URL을 확인합니다. 프리셋 주소가 잠겨 있으면 다른 엔드포인트를 입력하기 전에 사용자 지정 URL 옵션을 사용하세요.
- 사용 가능한 목록에서 모델을 선택하거나 Custom 아래에 정확한 API 모델 ID를 입력합니다. 모델을 불러올 수 있는지는 서비스와 계정에 따라 달라집니다.
- Test를 실행합니다. 응답을 확인하세요. 테스트 성공은 이 소규모 요청이 정상임을 확인할 뿐, 모든 도구, 미디어 모델 또는 향후 요청까지 검증하지는 않습니다.
- 저장 완료 확인이 표시될 때까지 기다립니다. 설정을 다시 열어 제공업체, 주소 및 모델을 확인한 다음 프로젝트로 돌아가 소규모 작업을 보내기 전에 해당 연결을 선택하세요.
키를 비공개로 유지하세요. 로컬에서 확인할 때는 Show로 필드 내용을 표시할 수 있지만, 스크린샷을 공유하기 전에는 반드시 가리세요.
예시: DeepSeek
DeepSeek Platform에서 키를 생성하세요. 기본 URL로 https://api.deepseek.com을 사용하고 계정에서 호출할 수 있는 모델을 선택합니다. 모델 ID(예: deepseek-flash)는 제공업체의 현재 모델 목록에서 확인하세요. 다만, 설치된 클라이언트의 스크린샷에는 여전히 이전 프리셋 별칭이 표시됩니다. 필요한 경우 현재 ID를 사용자 지정 모델로 입력하세요. 설치된 0.25.0 버전의 Get key 바로가기는 잘못된 제공업체 페이지를 열 수 있습니다. 관련 없는 OpenAI 키를 생성하지 말고 해당 제공업체의 콘솔을 사용하세요.
| 필드 | DeepSeek 직접 연결 예시 |
|---|---|
| 제공업체 / 프로토콜 | DeepSeek 프리셋 또는 OpenAI 프로토콜과 호환되는 사용자 지정 프리셋 |
| API Key | DeepSeek Platform 계정에서 발급한 키 |
| Base URL | https://api.deepseek.com |
| Model ID | 계정에 활성화된 경우 deepseek-flash |
오래된 스크린샷의 표시 이름을 사용하지 말고 현재 DeepSeek API 문서에서 정확한 ID를 복사하세요. 이 OpenAI 프로토콜 예시에서는 별도의 /anthropic 엔드포인트를 사용하지 마세요.
예시: OpenRouter
OpenRouter의 키 설정에서 키를 생성하세요. https://openrouter.ai/api/v1을 사용합니다. 제공업체 접두사를 포함하여 OpenRouter의 사용 가능한 모델 목록에서 모델 ID를 복사하세요. Anthropic 또는 OpenAI에서 직접 발급한 키를 OpenRouter 프리셋에 입력하지 마세요. 키는 요청을 수신하는 게이트웨이에서 발급한 것이어야 합니다.
- API providers에서 OpenRouter를 선택하고 OpenRouter에서 발급한 키를 붙여 넣습니다.
- Base URL로 https://openrouter.ai/api/v1을 사용합니다.
- 제공업체 접두사를 포함하여 OpenRouter 모델 디렉터리에서 정확한 모델 ID를 복사합니다.
- 연결을 테스트하고 저장될 때까지 기다린 다음, 요청을 실행하기 전에 프로젝트에서 해당 연결을 선택합니다.
다른 제공업체 확인하기
| 항목 | 확인할 내용 |
|---|---|
| 프로토콜 | 프리셋이 문서에 명시된 API 프로토콜과 일치해야 합니다. |
| Base URL | 대시보드 경로나 중복된 버전 경로 없이 프리셋에서 요구하는 API 루트를 사용하세요. |
| 모델 | 마케팅용 이름이 아니라 API 모델 ID를 사용하세요. |
| 권한 | 제공업체 계정에서 모델 액세스 권한, 지역별 제공 여부, 할당량 및 결제 상태를 확인하세요. |
키가 전체 실행 환경을 구성하는 것은 아닙니다
BYOK 작업에도 에이전트의 파일 및 도구 작업을 수행하는 지원 런타임이 필요합니다. 앱에서 런타임을 사용할 수 없다고 표시하면 해당 런타임의 설치 또는 재검색 안내를 따르세요. 키를 교체해도 실행 파일은 설치되지 않습니다.
청구 방식 이해하기
BYOK 요청 요금은 입력한 키를 발급한 제공업체 또는 게이트웨이에서 청구합니다. OpenDesign 구독과 외부 제공업체의 잔액은 서로 별개입니다. 유효한 키로도 작업을 실행할 수 없다면 청구 및 연결 문제 해결을 참조하세요.
테스트 결과 확인 및 문제 해결하기
| 결과 | 다음 조치 |
|---|---|
| 401 / 잘못된 키 | 키를 발급한 서비스를 확인하고 추가 형식 없이 전체 키를 붙여 넣으세요. 폐기된 키는 발급처에서 교체하세요. |
| 403 / 액세스 거부 | 제공업체에서 모델 권한, 지역 및 계정 액세스 권한을 확인하세요. 유효한 비밀 키만으로는 모델 액세스 권한이 부여되지 않습니다. |
| 404 / 모델을 찾을 수 없음 | API 루트와 정확한 모델 ID를 확인하세요. 대시보드 경로와 중복된 /v1 경로를 제거하세요. |
| 429 / 할당량 또는 요청 속도 제한 | 제공업체 오류를 확인하여 잔액 소진과 일시적인 요청 속도 제한을 구분하세요. 다시 시도하기 전에 해당 계정 콘솔을 확인하세요. |
| 시간 초과 / 네트워크 오류 | 클라이언트 환경에서 이 엔드포인트에 연결할 수 있는지 확인하세요. 네트워크 문제를 해결한 후 소규모 요청을 다시 시도하세요. |
테스트에 성공한 후 기존 프로젝트에서 소규모 요청 하나를 보내고 응답과 생성된 파일을 확인하세요. 테스트는 통과하지만 파일 작업이 실패한다면 실행 환경 섹션에 설명된 런타임을 확인하세요. 정상 작동하는 키를 반복해서 교체하지 마세요.