Chat Completions API란? messages로 AI 대화 요청하는 법 쉽게 이해하기
“내 프로그램에서도 AI에게 질문하고 답변을 받게 만들 수 있을까요?”
웹사이트에서 ChatGPT와 대화할 때는 질문을 입력하고 답변을 확인하면 됩니다. 하지만 블로그 도구나 간단한 프로그램에서 AI 모델을 사용하려면 프로그램이 어떤 형식으로 질문을 보내고 결과를 받을지 정해져 있어야 합니다.
그 방법 가운데 하나가 Chat Completions API입니다.
Chat Completions API는 사용자·AI의 대화 내용을 messages 목록으로 보내면 모델이 다음 응답을 생성해 돌려주는 API 인터페이스입니다. 정해진 데이터 형식으로 메시지를 전달하기 때문에 별도의 프로그램에서도 대화형 AI 기능을 구현할 수 있습니다.
어렵게 보일 수 있지만 원리는 단순합니다. 이전 대화 기록을 함께 적은 쪽지를 AI에게 보내고, AI가 그다음에 할 말을 받아오는 방식입니다.
이 글은 실제 API 계정 없이도 구조를 이해할 수 있게 JSON 예시와 역할 구분, 자주 발생하는 오류, FreeLLMAPI에서의 활용 방식까지 차례로 설명합니다.
이 글의 순서
- 1. 이름부터 나눠서 보면 쉽습니다
- 2. 가장 중요한 messages 는 무엇인가요?
- 3. role 은 누구의 말인지 구분합니다
- 4. 이전 대화가 왜 메시지에 들어가야 할까요?
- 5. 실제 API 주소는 어디인가요?
- 6. 답변은 어떤 모양으로 돌아오나요?
- 7. Python 코드에서는 어떻게 보일까요?
- 8. 채팅이 아니라 도구를 사용하게 할 수도 있나요?
- 9. Responses API와는 무엇이 다를까요?
- 10. 자주 나오는 오류와 점검 방법
- 11. 초보자라면 이렇게 배우면 됩니다
- 자주 묻는 질문 (FAQ)
- 마무리: messages를 이해하면 Chat Completions가 보입니다
- 공식 자료
1. 이름부터 나눠서 보면 쉽습니다
Chat은 대화, Completions는 제공된 문맥 다음에 이어질 텍스트나 응답의 생성을 뜻합니다. 이 API는 ‘대화형 메시지 묶음을 입력받아 다음 응답을 만드는 방식’이라고 이해하면 됩니다. 여기서 API는 프로그램이 다른 서비스에 기능을 요청하기 위한 약속된 접점입니다. 웹 채팅 화면을 직접 누르지 않아도 코드가 메시지를 전달하도록 도와줍니다. 예를 들어 ‘회의 내용을 두 문장으로 요약해줘’라는 질문을 보내면, 모델은 지정한 형식의 응답을 돌려줄 수 있습니다. 단, 실제 결과는 사용 모델·입력과 설정에 따라 달라집니다. 중요한 점 하나: Chat Completions API는 한 API 요청 방식의 이름입니다. ChatGPT 앱의 모든 기능이나 모든 OpenAI API가 동일한 요청 구조로 동작한다는 뜻은 아닙니다.
2. 가장 중요한 messages는 무엇인가요?
Chat Completions API의 핵심은 messages라는 순서 있는 메시지 배열입니다. 배열은 같은 종류의 항목을 여러 개 차례로 담아 놓은 목록이라고 생각하면 됩니다.
메시지마다 주로 role과 content 같은 정보가 있습니다. role은 누가 남긴 말인지, content는 그 말의 내용입니다.
가장 단순한 사례는 질문 하나를 담은 메시지입니다.
{
"model": "MODEL_ID_FROM_PROVIDER",
"messages": [
{"role": "user", "content": "안녕하세요. 두 문장으로 인사해 주세요."}
]
}
이 예시의 MODEL_ID_FROM_PROVIDER는 실제 모델명이 아니라 설명용 자리표시자입니다. 실제 연결 시에는 이용하는 제공업체의 공식 모델 목록에서 사용 가능한 ID를 확인해 바꿔야 합니다.
위 JSON에서 큰 중괄호는 요청 내용 전체, 대괄호는 메시지 목록, model은 요청을 처리할 모델 선택 항목입니다.
중요: 이 JSON을 화면에서 보는 것만으로 API가 실행되는 것은 아닙니다. 실제로 전송하려면 해당 서비스의 서버 주소, 인증 키, 이용 권한과 네트워크 연결이 필요합니다.
3. role은 누구의 말인지 구분합니다
Chat Completions 메시지는 여러 역할로 구성될 수 있습니다. 초보자는 다음 네 가지만 먼저 이해해도 충분합니다.
| role | 쉬운 의미 | 대화 속 역할 |
|---|---|---|
| developer | 앱 개발자가 설정한 지침 | 답변 형식·업무 규칙 안내 |
| user | 사용자의 요청 | 질문과 입력 자료 |
| assistant | AI가 앞서 작성한 메시지 | 이전 답변 또는 도구 호출 요청 |
| tool | 외부 도구의 실행 결과 | 실제로 실행한 도구의 반환값 |
예를 들어 식당의 주문서를 떠올려보세요. 운영 규칙을 적은 안내문, 고객 주문, 주문을 확인한 직원의 답변, 주방에서 확인한 재료 상황이 어떤 출처의 정보인지 구별되면 대화가 훨씬 이해하기 쉬워집니다.
이전에 작성된 오래된 예제에는 system 역할이 자주 나옵니다. OpenAI는 최신 일부 모델, 특히 o1 계열 이후의 모델에서는 개발자 지침에 developer 역할을 사용하도록 안내합니다. 모든 모델·모든 호환 업체가 똑같이 역할을 처리한다고 가정하지 말아야 합니다.
4. 이전 대화가 왜 메시지에 들어가야 할까요?
이 API를 이해할 때 매우 중요한 특징입니다. 일반적인 Chat Completions 요청은 해당 요청에서 모델이 참고할 대화 문맥을 messages에 직접 포함해 보내는 방식입니다.
가상으로 이런 대화를 했다고 가정하겠습니다.
사용자: ‘우리 동아리 이름은 별빛 과학 모임이야.’
AI: ‘좋아요. 별빛 과학 모임을 기억하며 이어서 이야기할게요.’
사용자: ‘그 이름으로 초대 문구를 만들어줘.’
마지막 문장만 따로 보내면 어떤 이름을 의미하는지 모델이 모를 수 있습니다. 따라서 필요한 이전 메시지를 함께 배열에 넣어 맥락을 이어갑니다.
{
"model": "MODEL_ID_FROM_PROVIDER",
"messages": [
{"role": "user", "content": "우리 동아리 이름은 별빛 과학 모임이야."},
{"role": "assistant", "content": "좋아요. 동아리 이름을 알려주셨군요."},
{"role": "user", "content": "그 이름으로 짧은 초대 문구를 써줘."}
]
}
실제 서비스는 대화 기록을 저장하고 재전송하는 구현 방법이 다양합니다. 프로그램을 만든 사람은 어떤 문맥을 보낼지, 저장·삭제 정책이 무엇인지 판단해야 합니다. 메시지를 무작정 길게 누적하면 입력 토큰 사용량과 요청 비용, 모델이 처리할 수 있는 컨텍스트 길이 제한에 영향을 줄 수 있습니다.
5. 실제 API 주소는 어디인가요?
OpenAI의 Chat Completions 요청은 일반적으로 다음 HTTP 경로를 사용합니다.
POST https://api.openai.com/v1/chat/completions
POST는 서버에 생성 작업을 요청하는 HTTP 방식입니다. 여기서 /v1/chat/completions가 요청을 받는 경로입니다.
FreeLLMAPI처럼 OpenAI 형식을 구현한 로컬 라우터에서는 제공업체 공식 문서에 다음 주소를 안내합니다.
POST http://localhost:3001/v1/chat/completions
두 주소의 요청 모양이 비슷해도 실제로 데이터를 받는 서비스는 서로 다릅니다. 앞의 것은 OpenAI 플랫폼, 뒤의 것은 내 컴퓨터에 설치·실행한 FreeLLMAPI 로컬 라우터입니다. 로컬 라우터도 최종 AI 추론 요청을 외부 모델 제공업체로 전달할 수 있습니다.
여기서 localhost는 해당 프로그램을 실행하는 기기 자신을 가리키므로, FreeLLMAPI가 실행되지 않았다면 주소만 복사해도 동작하지 않습니다.
6. 답변은 어떤 모양으로 돌아오나요?
정상 응답에는 보통 요청 ID, 모델, 생성 결과인 choices, 사용량인 usage 같은 정보가 포함될 수 있습니다.
아래는 구조를 설명하기 위해 단순화한 가상 응답 예시입니다.
{
"choices": [
{
"index": 0,
"message": {"role": "assistant", "content": "안녕하세요! 반갑습니다."},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 18,
"completion_tokens": 12,
"total_tokens": 30
}
}
choices[0].message.content는 일반적인 텍스트 응답 사례에서 읽고 싶은 AI 답변 문장에 해당합니다. usage는 요청과 응답에 사용한 토큰 수를 이해할 때 도움이 됩니다.
finish_reason에 stop이 나오면 일반적으로 정상 종료, length라면 길이 제한으로 중단됐을 수 있고, tool_calls라면 모델이 도구 호출이 필요하다고 요청한 상태일 수 있습니다.
이 데이터는 설명을 위한 가상 값이며 실제 실행한 API의 결과가 아닙니다. 모든 응답에서 message.content가 반드시 일반 텍스트로 차 있는 것은 아닙니다.
7. Python 코드에서는 어떻게 보일까요?
Python을 처음 배우는 분에게는 아래 예제가 API가 실제 프로그램과 연결되는 방식을 보여줍니다.
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
answer = client.chat.completions.create(
model="MODEL_ID_FROM_PROVIDER", # 실제 지원 모델 ID로 교체
messages=[
{"role": "user", "content": "AI API를 한 문장으로 설명해 주세요."}
],
)
print(answer.choices[0].message.content)
실행하려면 Python과 OpenAI 공식 SDK, 본인 계정의 API 권한·결제 조건 및 현재 지원되는 모델 ID가 필요합니다. 이 코드는 설명용이며 이 글을 작성하면서 실행하지 않았습니다.
API 키는 절대로 블로그 글·GitHub 저장소나 공유 스크린샷에 직접 적지 말고, 공식 키 관리 방식과 환경변수 같은 안전한 저장 방법을 사용하세요.
FreeLLMAPI를 사용한다면 공식 클라이언트 문서에 따라 base_url을 http://localhost:3001/v1로, 인증에는 FreeLLMAPI가 발급한 통합 API 키를 설정하는 방식이 있습니다. OpenAI 원본 키와 FreeLLMAPI 통합 키를 동일하다고 생각하면 안 됩니다.
8. 채팅이 아니라 도구를 사용하게 할 수도 있나요?
Chat Completions는 단순한 텍스트 답변 이외에 도구 호출과 스트리밍 등의 요청 형태를 지원하는 모델이 있습니다.
예를 들어 ‘서울의 날씨를 알려줘’라고 했을 때 모델이 사용할 수 있는 get_weather 도구를 요청했다고 가정하겠습니다. 이 경우 모델의 출력에 도구를 호출하라는 제안이나 인수가 나타날 수 있습니다.
그러나 이 출력만으로 실제 날씨 정보가 조회되는 것은 아닙니다. 프로그램이 허용된 도구를 직접 호출한 다음 결과를 tool 역할 메시지로 돌려주는 단계가 필요합니다.
다른 경우에는 stream=true로 응답 문장을 한 번에 받지 않고 조금씩 받아 화면에 표시할 수 있습니다.
주의할 점은 모든 호환 AI 공급업체가 이미지·도구·스트리밍·구조화 출력 등 모든 기능을 완벽하게 지원하는 것은 아니라는 것입니다.
9. Responses API와는 무엇이 다를까요?
OpenAI는 Chat Completions 이외에 Responses API라는 다른 생성 인터페이스도 제공합니다.
| 항목 | Chat Completions | Responses |
|---|---|---|
| 대표 입력 | messages 배열 | input 중심 |
| 대표 호출 | /v1/chat/completions | /v1/responses |
| 대표 반환 | choices의 메시지 | output 항목과 응답 내용 |
| 호환성 | 많은 기존 OpenAI 호환 앱이 사용 | 지원하는 SDK·서비스 별도 확인 |
두 인터페이스는 서로 다른 요청·응답 데이터 구조를 사용합니다. messages만 단순히 input으로 이름을 바꾼다고 모든 기능과 데이터가 완전히 일치한다고 생각하면 안 됩니다.
OpenAI의 최신 텍스트 생성 가이드는 새 통합·앱 개발에 Responses API 사용을 권장하는 방향을 안내하고 있습니다. 그렇다고 Chat Completions가 전혀 쓸 수 없다는 뜻은 아니며, 기존 앱과 OpenAI 호환 게이트웨이에서 널리 사용되는 형식입니다.
특히 FreeLLMAPI의 공식 지원 목록은 Codex CLI가 Responses 형식을 사용하는 반면, 여러 일반 OpenAI 호환 클라이언트는 Chat Completions 형식을 사용한다고 구분합니다.
10. 자주 나오는 오류와 점검 방법
401 / 인증 오류: API 키가 잘못됐거나 해당 서버에 유효하지 않은 키를 사용했을 수 있습니다. OpenAI 키와 라우터 통합 키를 구분하세요.
404 / 모델 또는 주소 오류: 존재하지 않는 경로나 사용 불가능한 모델 ID를 요청했을 수 있습니다. 공식 endpoint와 현재 모델 목록을 확인하세요.
429 / 요청 한도: 계정·모델의 속도 제한 또는 잔여 사용량이 원인일 수 있습니다. 무한 반복 요청하지 말고 공식 재시도 안내를 따르세요.
응답 내용이 비어 있음: 도구 호출 요청·거부·길이 제한 등 다양한 가능성을 확인하세요. 무조건 장애라고 단정하지 말고 finish_reason, 응답 구조 및 오류를 확인합니다.
가짜 성공·예상과 다른 모델: 라우터를 사용한다면 실제 처리한 제공업체·모델과 로그를 확인하세요. model="auto"는 라우터가 모델을 선택하는 FreeLLMAPI용 예제이지 OpenAI API에서 항상 유효한 일반 모델 ID는 아닙니다.
11. 초보자라면 이렇게 배우면 됩니다
먼저 messages에 user 메시지 하나만 있는 JSON 요청을 읽어보세요. 다음으로 assistant 답변이 하나 추가됐을 때 이전 대화를 어떻게 이어가는지 확인합니다.
세 번째로 choices[0].message.content 같은 반환 위치를 찾아보고, 네 번째로 usage와 finish_reason이 뜻하는 바를 익힙니다.
마지막으로 실제 API를 사용할 필요가 있을 때만 공식 SDK와 테스트 계정의 허용된 사용량을 확인하세요. 실제 키를 공유하거나 알 수 없는 서버에 인증정보를 붙여 넣는 일은 피하는 것이 좋습니다.
처음부터 복잡한 도구 호출이나 여러 AI 제공업체를 연결할 필요는 없습니다. 짧은 질문 하나를 어떤 형식으로 보내고 어떤 구조로 답을 받는지 이해하는 것이 목적입니다.
자주 묻는 질문 (FAQ)
Q1. Chat Completions API는 ChatGPT 웹사이트인가요?
아닙니다. ChatGPT는 이용자용 앱이고 Chat Completions는 프로그램이 대화형 AI에 요청하는 API 인터페이스입니다.
Q2. messages에 질문 하나만 담아도 되나요?
네. 기본적인 대화 생성 요청은 사용자 메시지 하나로 시작할 수 있습니다.
Q3. role: user와 role: assistant는 무엇이 다른가요?
사용자가 한 말과 AI가 생성한 말의 출처를 구분합니다.
Q4. 모든 요청에 이전 대화를 꼭 다시 넣어야 하나요?
현재 요청에서 필요한 대화 문맥을 포함해야 합니다. 저장·재전송 구현은 사용하는 앱과 API 방식에 따라 달라집니다.
Q5. model은 아무 이름이나 써도 되나요?
아닙니다. 실제 제공업체에서 지원하는 모델 ID를 확인해야 합니다.
Q6. choices[0]은 무엇을 뜻하나요?
일반적인 응답의 생성 후보 목록에서 첫 번째 항목을 가리킵니다.
Q7. API의 응답이 비어 있으면 실패한 것인가요?
항상 그렇지는 않습니다. 도구 호출, 거부, 길이 제한 등 응답 구조와 종료 사유를 확인해야 합니다.
Q8. Chat Completions와 Responses API는 같은가요?
아닙니다. 요청·응답 구조와 지원되는 기능이 다른 별도 API 인터페이스입니다.
Q9. FreeLLMAPI에서 OpenAI API 키를 그대로 넣어야 하나요?
보통 FreeLLMAPI에 연결된 클라이언트는 라우터가 발급한 통합 키를 사용합니다. 원래 공급업체 키와 혼동하지 마세요.
Q10. 처음 연습할 때 돈이 나가나요?
실제 API 호출에는 각 제공업체의 현재 무료·유료 조건이 적용됩니다. 코드를 읽기만 하는 예시 학습에는 실제 요청 비용이 발생하지 않습니다.
마무리: messages를 이해하면 Chat Completions가 보입니다
Chat Completions API의 핵심은 ‘누가 말했는지’ 구분된 대화 메시지 목록을 모델에 보내고, 모델이 만든 응답을 받는 것입니다.
role, content, messages, model, choices 다섯 단어만 알아도 많은 Chat Completions 예제의 구조가 보이기 시작합니다.
다만 실제 사용 때에는 정확한 모델 ID, 인증정보 관리, 서비스별 호환성과 사용 요금·개인정보 정책을 확인하세요. 같은 JSON 모양으로 요청을 보낼 수 있다고 해서 모든 제공업체에서 같은 기능과 비용이 보장되는 것은 아닙니다.
공식 자료
제품의 동작과 제한은 바뀔 수 있으므로 게시 시점에도 공식 문서에서 다시 확인하세요.
함께 읽으면 좋은 글
- API란 무엇일까? 앱과 AI가 연결되는 원리 쉽게 설명 — 용어의 기본 정의와 범위를 이어서 확인할 수 있습니다.
- AI 토큰이란? ChatGPT를 오래 쓰면 사용량이 늘어나는 이유 쉽게 설명 — 용어의 기본 정의와 범위를 이어서 확인할 수 있습니다.