사용자 지정 API 엔드포인트: OpenAI 호환 API 연결 방법
사용자 지정 API 엔드포인트와 Base URL이 무엇인지, OpenAI 호환 API·릴레이·프록시·게이트웨이를 주소와 키만으로 연결하는 방법을 설명합니다.
- 사용자 지정 API 엔드포인트(custom endpoint)는 앱에 기본으로 들어 있지 않은 AI 서비스의 웹 주소, 즉 Base URL(요청 URL)입니다. OpenAI 호환 API, 릴레이, 프록시, 게이트웨이가 여기에 해당합니다. Oriveo에서 연결할 때는 대개 이 주소와 API 키, 두 가지만 있으면 됩니다.
- Oriveo가 프로토콜(OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini)을 알아서 판단하고, 루트 주소만 입력하면 /v1 같은 버전 경로를 붙여 줍니다.
- 공용 주소는 HTTPS여야 합니다. 제3자 서비스는 그곳을 거쳐 가는 모든 내용을 볼 수 있으므로, 지출 한도를 건 별도 키를 쓰고 공식 제공업체 키는 절대 넘기지 마세요.

Base URL 또는 API 엔드포인트란?
모든 AI 서비스에는 앱이 요청을 보내는 웹 주소가 있습니다. 개발자들은 이를 Base URL, API 엔드포인트, 요청 URL이라고 부르는데, 여기서는 모두 같은 뜻입니다. 생김새는 평범한 웹 주소와 같습니다. 예를 들어 OpenAI의 주소는 https://api.openai.com/v1입니다.
Oriveo에서는 기본 탑재된 제공업체 15곳의 주소가 이미 채워져 있어 키만 붙여 넣으면 됩니다. 사용자 지정 엔드포인트는 그 밖의 모든 경우를 위한 것입니다. OpenAI 호환 API를 제공하는 서비스, 회사가 운영하는 릴레이나 게이트웨이, 내 서버에서 직접 운영하는 게이트웨이 등이 해당합니다.
"OpenAI 호환(OpenAI-compatible)"이란 서비스가 OpenAI API와 같은 형식의 요청을 받는다는 뜻으로, 덕분에 OpenAI용으로 만든 앱이 그 서비스와 통신할 수 있습니다. 많은 제공업체와 게이트웨이가 이 형식을 지원합니다.
릴레이, 프록시, 게이트웨이는 무엇이 다른가요?
세 단어는 딱히 구분 없이 섞여 쓰이고, 앱을 연결할 때는 모두 똑같이 작동합니다. 앱과 모델 제공업체 사이에 서비스가 하나 있어 요청을 받아 넘겨주는 구조입니다. 여러 제공업체를 키 하나, 청구서 하나로 묶어 주는 곳도 있고, 팀을 위한 사용량 관리 기능을 더한 곳도 있고, 내 서버에서 직접 돌리는 소프트웨어도 있습니다.
Oriveo는 어느 서비스도 추천하거나 순위를 매기지 않습니다. 무엇을 쓰든 아래 순서는 같습니다.
사용자 지정 엔드포인트를 연결하려면 무엇이 필요한가요?
대개 두 가지이며, 둘 다 해당 서비스의 대시보드나 문서에서 얻습니다.
- 요청 URL(Base URL). 예: https://api.example.com/v1. 공용 인터넷에 있는 서비스라면 https://로 시작해야 합니다.
- 서비스가 나에게 발급한 API 키. "키 하나 더 추가"로 키를 더 넣을 수 있습니다.
- 선택 사항: 다른 연결과 구별하기 위한 연결 이름.
Oriveo에 사용자 지정 엔드포인트를 추가하는 방법
iPhone, Android, 웹 모두 순서가 같습니다.
- 제공업체를 열고 + 버튼(제공업체 추가)을 누릅니다.
- 사용자 지정 칩을 고른 뒤 사용자 정의 릴레이("내 모델 서비스에 연결")를 누릅니다.
- "사용자 정의 릴레이 연결" 화면에서 요청 URL과 API 키를 붙여 넣습니다. "요청 주소: …" 줄에 Oriveo가 실제로 쓸 전체 주소가 표시됩니다. 다음을 누릅니다.
- Oriveo가 연결을 확인하고 모델 목록을 읽은 뒤 모델별 프로토콜을 판단합니다. 이 단계에서는 목록만 읽고 채팅 메시지는 보내지 않습니다.
- 원하는 모델을 체크하고 "저장(N개 선택됨)"을 누릅니다. 서비스가 모델 목록을 제공하지 않으면 "모델 ID 직접 추가"를 쓰세요.
- 저장하기 전에 Oriveo가 선택한 첫 번째 모델에 아주 작은 요청을 한 번 보냅니다. 이 테스트를 통과하면 연결이 저장되고, 실패하면 같은 단계에 머물러 문제를 고칠 수 있습니다.

직접 모두 설정하고 싶다면: 수동 설정
수동 설정에서는 주소, 키, 모델 ID, 연결 이름(선택), 기본 프로토콜을 한 페이지에서 입력합니다. 기본 프로토콜은 처음에 자동으로 되어 있습니다. "확인하고 저장"을 누르세요. 확인에 실패하면 아직 아무것도 저장되지 않으며, 연결을 일단 보관해 두고 나중에 테스트하고 싶다면 실패 카드의 "확인되지 않은 상태로 저장"을 누르면 됩니다.
Oriveo가 프로토콜을 자동으로 감지하나요?
대부분 그렇습니다. AI 서비스는 프로토콜이라고 부르는 몇 가지 요청 형식 중 하나를 씁니다. Oriveo는 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, Gemini generateContent 네 가지를 지원합니다.
판단은 모델별로 합니다. 서비스가 모델에 대한 정보를 제공하면 그것을 쓰고, 없으면 모델 계열을 보고 가능성 높은 후보를 고릅니다. 저장할 때는 선택한 첫 번째 모델을 실제 요청으로 테스트하고, 나머지는 나중에 실제로 쓰기 시작할 때 확인합니다.
그래서 대부분은 주소와 키만으로 충분합니다. 서비스 문서에 특정 프로토콜이 적혀 있거나 어떤 모델이 확인에 실패하면, 수동 설정에서 프로토콜을 직접 고르세요.
주소에 /v1을 붙여야 하나요?
대개는 필요 없습니다. https://api.example.com처럼 루트 주소만 입력하면 Oriveo가 프로토콜에 맞는 표준 버전 경로를 붙입니다. OpenAI·Anthropic 형식은 /v1, Gemini는 /v1beta입니다.
/api/paas/v4처럼 주소에 이미 버전이 들어 있으면 그대로 둡니다. /chat/completions, /responses, /messages, :generateContent로 끝나는 전체 엔드포인트를 붙여 넣으면 Oriveo가 그 끝부분을 떼어 내고, 이를 근거로 서비스가 어떤 프로토콜을 쓰는지 판단합니다.
다음을 누르기 전에 "요청 주소: …" 줄을 확인하세요. 확인 결과 "주소가 웹 페이지를 가리키고 있을 수 있습니다. /v1이 빠지지 않았는지 확인하세요."가 나오면 주소를 서비스 문서와 비교해 보세요.
| 입력한 주소 | Oriveo가 요청하는 주소(OpenAI 형식) |
|---|---|
| https://api.example.com | https://api.example.com/v1 |
| https://api.example.com/v1 | https://api.example.com/v1 |
| https://api.example.com/v1/chat/completions | https://api.example.com/v1, Chat Completions 사용 |
| https://api.example.com/api/paas/v4 | https://api.example.com/api/paas/v4 |
어떤 주소를 쓸 수 있나요?
Oriveo는 키를 보호하기 위해 몇 가지 규칙을 따릅니다.
- 공용 주소는 https://로 시작해야 합니다. 공용 인터넷의 http:// 주소는 테스트하거나 저장할 수 없습니다.
- 주소 안에 사용자 이름과 비밀번호가 들어 있거나 쿼리 매개변수("?" 뒤의 모든 것)가 있으면 받지 않습니다. Oriveo는 쿼리 매개변수에 든 API 키를 시도하지 않습니다.
- 내 컴퓨터의 모델 서버처럼 집 네트워크나 사설 VPN에 있는 일반 http:// 주소는 사용자 정의 릴레이가 아니라 별도의 로컬 컴퓨팅 항목(iPhone: "로컬 및 LAN 컴퓨팅")으로 연결합니다.
- iPhone과 Android에서는 앱이 주소에 직접 연결합니다.
- 웹 앱에서는 브라우저의 CORS 제한(브라우저가 많은 직접 요청을 막는 보안 규칙)을 우회하기 위해 공용 요청 URL이 Oriveo 서버를 거쳐 전달됩니다. API 키는 해당 요청 동안 메모리에서만 사용되며 저장되거나 기록되지 않습니다. 로컬 네트워크의 주소는 기기에서 직접 연결되며, 두 경우 모두 HTTPS가 필요합니다. 집 네트워크의 일반 http:// 주소를 쓰려면 iPhone이나 Android 앱의 로컬 컴퓨팅 항목을 이용하세요.
- 키는 이 기기에만 저장되며 클라우드 동기화로 업로드되지 않습니다.
기본 제공업체의 Base URL
Oriveo에서는 이 주소가 필요 없습니다. 제공업체 이름을 고르기만 하면 됩니다. 다른 도구에 쓰려고 찾아보는 사람이 많아 정리해 두었습니다. 모두 2026년 11월 18일 기준 각 제공업체 문서에 나온 공식 OpenAI 호환 주소입니다.
- Anthropic은 자사 OpenAI 호환 계층을 테스트와 비교용이라고 설명하고, Mistral 빠른 시작 문서는 자사 API를 OpenAI 호환이라고 설명하지 않습니다. 이 둘은 기본 제공업체로 추가하세요.
| 제공업체 | OpenAI 호환 Base URL |
|---|---|
| OpenAI | https://api.openai.com/v1 |
| Google Gemini | https://generativelanguage.googleapis.com/v1beta/openai/ |
| OpenRouter | https://openrouter.ai/api/v1 |
| DeepSeek | https://api.deepseek.com |
| xAI (Grok) | https://api.x.ai/v1 |
| Groq | https://api.groq.com/openai/v1 |
| Together AI | https://api.together.ai/v1 |
| Fireworks AI | https://api.fireworks.ai/inference/v1 |
| MiniMax(국제) | https://api.minimax.io/v1 |
| Z.ai(국제) | https://api.z.ai/api/paas/v4/ |
| Qwen(싱가포르 리전) | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
| Kimi(국제) | https://api.moonshot.ai/v1 |
| SiliconFlow(국제) | https://api.siliconflow.com/v1 |
릴레이나 제3자 API를 써도 안전한가요?
주의가 필요합니다. 나와 모델 사이에 있는 서비스는 프롬프트, 첨부 파일, 답변을 모두 읽을 수 있고, 가격도 스스로 정합니다. Oriveo는 그 내부를 들여다볼 수도, 보증할 수도 없습니다.
- 공식 제공업체 계정의 API 키를 제3자 서비스에 절대 넘기지 마세요. 그 서비스가 나에게 발급한 키를 쓰세요.
- Oriveo용 키를 따로 만들고, 서비스가 허용한다면 지출 한도를 걸거나 잔액을 적게 유지하세요.
- 믿을 수 없는 서비스로 비밀번호, 신분증 번호, 회사 기밀을 보내지 마세요.
- 사용량은 서비스 자체 대시보드에서 확인하세요. Oriveo의 비용 수치는 예상치이며, 서비스의 기록이 최종 기준입니다.
- 키가 유출되면 서비스 대시보드에서 삭제하고 새로 만드세요.
사용자 지정 엔드포인트가 연결되지 않는 이유는?
Oriveo는 무엇이 잘못됐는지 한 줄로 알려 줍니다. 한국어 화면에 표시되는 메시지는 다음과 같습니다.
- 401, 402, 429 같은 코드가 각각 무슨 뜻인지는 API 키 오류 가이드에서 설명합니다.
| Oriveo 메시지 | 확인할 것 |
|---|---|
| 주소가 웹 페이지를 가리키고 있을 수 있습니다. /v1이 빠지지 않았는지 확인하세요. | 주소를 서비스 문서와 비교하고 버전 경로를 붙이거나 뺍니다 |
| 키가 유효하지 않습니다. | 서비스 대시보드에서 키를 다시 복사합니다 |
| 이 키에는 모델 목록을 볼 권한이 없습니다. 모델을 직접 추가할 수 있습니다. | 다음 단계에서 모델 ID를 직접 추가합니다 |
| 연결할 수 없습니다. 네트워크나 프록시를 확인하세요. | 인터넷 연결과 주소에 접속할 수 있는지 확인합니다 |
| 이 주소의 서비스에 요청 제한이 걸려 있습니다. | 잠시 기다렸다가 다시 시도합니다 |
| 이 연결이 상위 제공업체에 접속하지 못했습니다. | 그 뒤에 있는 서비스 자체 계정이 유효하지 않거나 크레딧이 없거나 속도 제한에 걸렸을 수 있습니다. 운영자에게 문의합니다 |