API 엔드포인트란? base URL·경로·GET·POST 차이 쉽게 이해하기
AI 프로그램의 설정 화면에서 이런 주소를 본 적 있나요?
http://localhost:3001/v1/chat/completions
처음 보면 주소가 너무 길고 복잡합니다. 인터넷 홈페이지 주소처럼 보이는데, 주소창에 붙여 넣으면 정상적으로 열리지 않을 때도 있습니다.
이 주소를 이해하는 핵심 단어가 API 엔드포인트(API Endpoint)입니다.
API 엔드포인트는 프로그램이 특정 기능이나 데이터를 요청하기 위해 접근하는 API의 구체적인 접점입니다. 보통 서버 주소와 요청 경로의 조합으로 표시되며, 실제로는 GET, POST 같은 HTTP 요청 방식도 함께 맞아야 합니다.
쉽게 말하면 큰 건물 안에서 내가 방문해야 할 정확한 창구입니다. 건물 주소만 안다고 민원서를 어디에 제출해야 하는지 알 수는 없겠죠. 어느 창구에 어떤 종류의 요청을 할지 알아야 합니다.
이 글은 URL을 한 부분씩 해석하고, OpenAI API와 FreeLLMAPI를 예시로 base_url, /v1, /chat/completions, HTTP 메서드의 차이까지 설명합니다.
이 글의 순서
1. API와 API 엔드포인트는 어떻게 다를까요?
API는 프로그램들이 기능과 데이터를 주고받기 위해 따르는 규칙과 접점의 묶음입니다. API 엔드포인트는 그중에서 특정 요청을 보내는 대상입니다. 예를 들어 하나의 AI 서비스에 모델 목록을 확인하는 기능과 AI 답변을 생성하는 기능이 있다고 생각해보세요.
| 구분 | 어떤 질문에 답하나요? | 비유 |
|---|---|---|
| API | 프로그램과 서버가 어떤 규칙으로 통신하나요? | 민원 업무 안내서 전체 |
| API 서버 | 요청을 받는 서비스는 어디에 있나요? | 건물 |
| 엔드포인트 | 구체적으로 어떤 주소·기능에 요청하나요? | 해당 업무의 창구 |
| HTTP 메서드 | 조회·제출 등 어떤 종류의 요청인가요? | 창구에 맡길 업무 종류 |
같은 서버라도 요청을 받는 경로가 다르면 기능도 달라질 수 있습니다. 반대로 동일한 경로에서도 서버가 허용하는 요청 방식이 다르면 결과가 달라질 수 있습니다.
2. 긴 URL을 다섯 조각으로 나눠보세요
다음 주소는 FreeLLMAPI 프로젝트 공식 문서에서 안내하는 기본 로컬 경로 예시입니다.
http://localhost:3001/v1/chat/completions
하나씩 나누면 다음과 같습니다.
| 구간 | 뜻 | 초보자 설명 |
|---|---|---|
| http:// | 프로토콜 또는 스킴 | 어떤 통신 방식을 쓰나요? |
| localhost | 호스트 이름 | 요청할 서버가 어느 기기에 있나요? |
| :3001 | 포트 번호 | 그 기기의 어느 네트워크 서비스인가요? |
| /v1 | 경로의 일부 | 이 서비스에서 버전 구분 등에 쓰는 경로 |
| /chat/completions | 기능 경로 | 대화형 AI 생성 요청을 받는 경로 |
/v1은 이 서비스에서 API 경로의 일부입니다. 모든 API가 반드시 /v1을 써야 한다거나 v1이라는 문자열만으로 정확한 호환성이 보장되는 것은 아닙니다.
중요: localhost는 요청을 보내는 컴퓨터 자신을 가리키는 이름입니다. FreeLLMAPI 프로그램이 내 컴퓨터에서 실행되지 않으면 위 주소가 자동으로 작동하지 않습니다. Docker 컨테이너 안에서 localhost를 사용하면 보통 그 컨테이너 자신의 네트워크 환경을 가리켜 호스트 컴퓨터와 달라질 수도 있습니다.
3. base URL과 API 엔드포인트는 같은 주소일까요?
base URL(기본 URL)은 API 주소 여러 개에서 공통으로 쓰는 앞부분을 말합니다. 개발 도구나 SDK가 뒤에 구체적인 기능 경로를 붙이도록 설정할 때 사용합니다. 예를 들어 FreeLLMAPI의 OpenAI 호환 클라이언트용 기본 URL은 다음과 같습니다.
base_url = http://localhost:3001/v1
채팅 답변을 생성하는 기능의 전체 요청 주소는 이렇게 됩니다.
http://localhost:3001/v1/chat/completions
즉, 이 예시에서 base_url은 여러 기능이 공통으로 사용하는 주소이고, 실제 요청 경로가 붙은 것이 해당 기능의 엔드포인트 URL입니다.
기본 주소 http://localhost:3001/v1
추가되는 경로 /chat/completions
완성된 주소 http://localhost:3001/v1/chat/completions
다른 기능을 호출할 때에는 같은 기본 주소 뒤에 /models 같은 경로가 붙을 수 있습니다.
주의: 모든 SDK가 URL을 합치는 방식이 같지는 않습니다. 어떤 도구는 base_url에 /v1을 포함해야 하고, 다른 도구는 루트 서버 주소만 요구할 수 있습니다. 설명서가 지정한 기본 URL을 그대로 사용하는 것이 안전합니다.
4. GET과 POST가 다른 이유
주소를 정확히 안다고 끝이 아닙니다. 어떤 동작을 요청하는지 알려주는 HTTP 메서드도 필요합니다. 두 가지 대표적인 방법을 살펴보겠습니다.
- GET: 서버에 정보나 자료를 요청해 받아오는 데 사용하는 방식입니다. 예를 들어 어떤 모델이 등록되어 있는지 목록을 읽는 요청입니다.
- POST: 서버에 데이터를 보내 처리하거나 새 결과를 생성하도록 요청하는 방식입니다. 예를 들어 내가 쓴 질문을 전송해 AI 답변을 생성하는 요청입니다. FreeLLMAPI 공식 REST API 문서에 기반한 예시는 다음과 같습니다.
GET http://localhost:3001/v1/models
POST http://localhost:3001/v1/chat/completions
여기서 GET이나 POST는 URL 속 글자가 아니라 요청 방식입니다.
브라우저 주소창은 일반적으로 GET 방식으로 페이지를 요청하기 때문에 POST가 필요한 생성 엔드포인트 주소를 복사해서 붙여 넣는 것만으로 원하는 결과가 나오지는 않습니다.
또한 POST는 항상 단순 조회라고 볼 수 없습니다. 서버에 따라 데이터를 저장하거나 외부 작업을 일으킬 수도 있으니 모르는 API 주소를 실제 키와 함께 시험하지 마세요.
5. 질문 본문(JSON)은 어디에 들어가나요?
AI에게 ‘안녕’이라는 질문을 보낼 때 엔드포인트 URL 자체에 질문을 써 넣을 필요는 없습니다. 일반적인 Chat Completions 형식에서는 서버에 보내는 요청 본문(body)에 JSON 데이터를 넣습니다.
{
"model": "auto",
"messages": [
{"role": "user", "content": "안녕하세요. 한 문장으로 답해 주세요."}
]
}
이 JSON은 FreeLLMAPI를 사용하는 예시입니다. 여기서 auto는 FreeLLMAPI 라우터가 연결된 후보 모델 중 하나를 선택할 때 사용하는 방식이며, 공식 OpenAI API에서 무조건 동작하는 일반 모델 ID가 아닙니다.
실제로 요청을 보내려면 올바른 POST 메서드, 인증키, Content-Type: application/json 같은 헤더와 정상 실행 중인 서버가 필요할 수 있습니다.
주소 = 어디로 보내나, 메서드 = 어떤 요청인가, 본문 = 무엇을 보내나로 구별하면 복잡한 설명도 훨씬 쉬워집니다.
6. 실제 OpenAI API와 로컬 FreeLLMAPI를 비교하면
이름에 ‘OpenAI 호환’이 들어 있다고 OpenAI 공식 서버와 같은 위치를 가리키는 것은 아닙니다. 예를 들어 Chat Completions 인터페이스의 공식 OpenAI 주소는 다음과 같습니다.
POST https://api.openai.com/v1/chat/completions
반면 FreeLLMAPI가 내 컴퓨터에서 실행되고 있을 때 관련 요청 주소는 다음과 같습니다.
POST http://localhost:3001/v1/chat/completions
두 주소의 끝부분이 같더라도 실제 요청을 받는 서버가 다릅니다. OpenAI 공식 주소에는 OpenAI 플랫폼 계정 및 해당 API에 유효한 인증·모델·요금 조건이 적용됩니다. FreeLLMAPI 로컬 주소에는 라우터의 통합 API 키와 연결한 원래 모델 제공업체의 정책·이용 한도가 적용됩니다. 또한 FreeLLMAPI는 로컬 컴퓨터에서 실행되더라도 AI 질문을 외부 모델 제공업체로 전달할 수 있습니다. 주소가 localhost라고 데이터가 모두 컴퓨터 안에서만 처리된다는 뜻은 아닙니다.
7. 같은 서비스인데 API 주소가 여러 개인 이유
하나의 AI 플랫폼에도 기능이 여러 개 있을 수 있습니다. 예를 들어 OpenAI의 대표적인 대화형 생성 방식에는 다음 두 가지 별도 경로가 있습니다.
POST /v1/chat/completions
POST /v1/responses
두 엔드포인트는 요청·응답 데이터 구조가 다릅니다. Chat Completions는 messages 배열을 중심으로, Responses는 input과 output 등의 구조를 중심으로 사용합니다.
따라서 두 URL의 기능이 비슷하다고 해서 요청 본문만 그대로 복사해 바꿔 붙이면 언제나 작동하는 것은 아닙니다.
FreeLLMAPI도 자체 REST API 문서에서 모델 목록·응답 생성·채팅 생성 등 다양한 경로를 설명합니다. 특정 클라이언트는 Responses를, 다른 클라이언트는 Chat Completions나 Anthropic Messages 형식을 요구할 수 있습니다.
먼저 사용 중인 앱이 어떤 API 형식을 지원하는지 확인하고, 그 형식에 맞는 기본 주소와 엔드포인트를 설정하는 것이 중요합니다.
8. URL 뒤에 ?가 붙으면 무엇을 뜻하나요?
API URL은 경우에 따라 쿼리 파라미터(Query Parameter)를 함께 사용합니다.
http://localhost:3001/v1/models?available=true
여기서 ? 뒤의 available=true는 모델 목록을 원하는 조건으로 필터링하려는 추가 정보입니다. 실제 필터의 이름·허용 값은 API마다 다릅니다.
경로(path)는 /v1/models, 쿼리(query)는 available=true로 나눠 읽을 수 있습니다.
사용하는 API가 지원하지 않는 쿼리를 임의로 붙이면 무시되거나 오류가 날 수 있습니다.
비밀번호나 API 키를 URL의 쿼리 부분에 넣지 마세요. URL은 브라우저 기록, 프록시 로그 또는 모니터링 도구에 남을 수 있습니다. FreeLLMAPI 공식 문서도 통합 API 키를 URL에 직접 넣지 말라고 안내합니다.
9. 잘못된 엔드포인트에서 흔히 나타나는 오류
| 표시되는 현상 | 가능한 원인 | 먼저 확인할 것 |
|---|---|---|
| 404 Not Found | 요청한 경로가 없거나 잘못됨 | 정확한 /v1/... 경로와 공식 API 버전 |
| 405 Method Not Allowed | 경로는 있지만 요청 방식이 맞지 않음 | GET인지 POST인지 |
| 401 Unauthorized | 인증 정보가 없거나 유효하지 않음 | 서비스에 맞는 인증키·헤더 |
| 403 Forbidden | 접근 권한이 부족하거나 거부됨 | 계정 권한·정책 |
| 연결 거부·타임아웃 | 서버가 꺼져 있거나 주소·포트·네트워크가 다름 | 프로그램 실행 여부, localhost와 네트워크 환경 |
이 표는 일반적인 문제 해결 단서입니다. 같은 상태 코드도 서비스에 따라 세부 원인이 다를 수 있어, 실제 오류 응답과 공식 문서를 함께 읽어야 합니다.
예를 들어 localhost:3001에 연결이 안 된다면 서버가 실행 중인지 먼저 확인하세요. 그 상태에서 외부 API를 무작정 수십 번 반복 호출하면 문제 해결보다 이용 한도나 비용 문제가 커질 수 있습니다.
10. 초보자용 5단계 API 주소 점검법
설정을 복사하기 전에 다음 다섯 가지를 확인하면 많은 실수를 피할 수 있습니다.
- 어디 서버인가요? 공식 OpenAI 서버인가요, 내 컴퓨터의 FreeLLMAPI 서버인가요, 아니면 별도 제공업체인가요?
- 기본 URL은 무엇인가요? 예제에서
/v1까지 포함하는지, 클라이언트가 경로를 자동으로 붙이는지 봅니다. - 정확히 어느 기능인가요? 모델 목록인지, 채팅 생성인지, Responses 요청인지 경로를 읽습니다.
- 어떤 메서드와 데이터 형식인가요? GET·POST, JSON 요청 본문·인증 헤더가 필요한지 확인합니다.
- 실제 접근할 수 있나요? 서버가 실행 중인지, 키가 맞는지, 계정·모델·요금 정책이 허용하는지 확인합니다. 처음 배우는 단계라면 개인정보를 담지 않은 예시 요청 구조만 읽는 것으로도 충분합니다. 실제 API를 사용할 때에만 본인에게 허용된 계정과 안전한 키 저장 방법을 사용하세요.
자주 묻는 질문 (FAQ)
Q1. API 엔드포인트는 웹사이트 주소와 같은 건가요?
URL 형태를 사용할 수 있지만 일반 웹페이지가 아니라 프로그램 요청을 받는 기능별 접점인 경우가 많습니다. 브라우저 주소창으로 열리지 않을 수도 있습니다.
Q2. base_url과 엔드포인트 URL은 같은가요?
보통 base URL은 공통 접속 주소이고 엔드포인트는 여기에 기능 경로를 더한 대상입니다. 실제 URL 조합은 사용하는 클라이언트마다 다를 수 있습니다.
Q3. /v1은 무슨 뜻인가요?
서비스가 API 버전을 구분하는 데 사용할 수 있는 경로입니다. 모든 API가 반드시 /v1을 사용하는 것은 아닙니다.
Q4. localhost:3001은 인터넷에서 누구나 접속할 수 있는 주소인가요?
아닙니다. 보통 해당 기기의 로컬 서비스로 연결됩니다. 컨테이너나 다른 기기에서 볼 때의 대상은 다를 수 있습니다.
Q5. GET과 POST는 어떤 차이가 있나요?
GET은 주로 자료를 요청하는 데, POST는 데이터를 보내 처리하도록 요청하는 데 사용합니다. 구체적 동작은 API 명세에 따라 다릅니다.
Q6. API 엔드포인트 주소를 바꾸면 무료 AI 모델도 바뀌나요?
반드시 그렇지는 않습니다. 대상 서버, 인증키, 연결 모델 및 제공업체 설정에 따라 달라집니다. 주소만으로 무료 권한이 생기지 않습니다.
Q7. OpenAI API 주소를 FreeLLMAPI의 로컬 주소로 바꾸면 모두 작동하나요?
아닙니다. 해당 클라이언트의 API 형식, 모델 지원, 인증키, 설정이 FreeLLMAPI와 호환되어야 합니다.
Q8. 404 오류가 나오면 API 서버가 무조건 고장 난 건가요?
아닙니다. 기능 경로의 오타나 버전 차이 등으로 요청한 위치를 찾지 못할 수 있습니다.
Q9. API 키를 주소 끝에 붙여도 되나요?
보안상 권장되지 않습니다. API 키를 URL에 넣으면 기록·로그에 노출될 수 있으므로 서비스가 요구하는 안전한 인증 헤더 방식을 따르세요.
Q10. 실제로 API를 연결해보려면 무엇부터 확인하나요?
공식 문서의 base URL, 정확한 경로·요청 방식, 지원 모델과 인증·비용·데이터 정책을 우선 확인하세요.
핵심 정리
API 엔드포인트는 특정 기능을 요청하는 정확한 접점입니다. 긴 주소도 프로토콜·호스트·포트·경로로 나누면 이해할 수 있습니다.
기억할 핵심은 세 가지입니다. base URL은 공통 주소, 엔드포인트는 구체적인 기능 경로, GET·POST는 요청 방식입니다.
그리고 같은 /v1/chat/completions라도 공식 OpenAI 서버와 로컬 FreeLLMAPI 서버는 서로 다른 서비스를 가리킵니다. 어디에 연결되는지와 인증·요금·데이터 전송 조건을 함께 확인하는 습관이 중요합니다.
함께 읽으면 좋은 글
- API란 무엇일까? 앱과 AI가 연결되는 원리 쉽게 설명 — 관련 개념과 실전 점검 방법을 함께 확인합니다.
- CLI란? 명령어로 컴퓨터를 다루는 방법과 초보자 예시 — 관련 개념과 실전 점검 방법을 함께 확인합니다.