OpenAI Chat Completions API: 기능 및 사용 가이드

AI 기반 애플리케이션을 구축하는 일은 단순히 모델이 응답을 생성하게 하는 것만으로 끝나지 않습니다. 대화를 관리하고, 응답을 유도하며, 모든 요소를 애플리케이션에 연결할 안정적인 방법도 필요합니다. OpenAI Chat Completions API는 AI가 메시지를 처리하고 답변을 생성하는 방식을 개발자가 제어할 수 있게 해 이를 가능하게 합니다. 작동 방식과 자체 프로젝트에서의 활용법을 알고 싶다면, 이 글에서 필요한 내용을 모두 안내합니다.

OpenAI Chat Completions API를 사용하면 개발자는 OpenAI의 언어 모델을 애플리케이션과 서비스에 통합할 수 있습니다. 일련의 메시지를 바탕으로 응답을 생성하며, 대화, 질의응답, 콘텐츠 생성, 텍스트 분석 등의 작업을 지원합니다.

Chat Completions는 계속 지원됩니다. 새 프로젝트에는 OpenAI가 Responses API를 권장합니다. 이 가이드에서는 Chat Completions의 메시지 형식, 요청 매개변수, 호환 SDK에서의 사용 방법을 설명합니다.

텍스트 프롬프트를 받는 기존 Completions 엔드포인트(/v1/completions)와 달리, Chat Completions는 구조화된 메시지 목록을 받습니다. 각 메시지에는 developer, user, assistant와 같은 역할이 있으며, 이를 통해 모델은 지침과 대화 맥락을 해석합니다. 지원되는 역할과 콘텐츠 유형은 선택한 모델에 따라 다릅니다.

개발자는 API를 사용해 다음과 같은 다양한 AI 기반 기능을 구축할 수 있습니다:

• 대화형 애플리케이션: 사용자 메시지에 응답하는 AI 챗봇, 가상 비서, 고객 지원 시스템을 만듭니다.

• 콘텐츠 생성: 기사, 제품 설명, 이메일, 요약문 등 다양한 글을 생성합니다.

• 텍스트 분석: 텍스트를 분류하고, 정보를 추출하며, 감정을 분석하고, 문서의 핵심 요점을 식별합니다.

• 코딩 지원: 코드 스니펫을 생성하고, 프로그래밍 개념을 설명하며, 개발자의 오류 해결을 돕습니다.

• 언어 처리: 여러 언어의 텍스트를 번역, 재작성, 단순화, 교정합니다.

이 API는 언어 모델을 기존 소프트웨어와 유연하게 연결하는 방법을 제공하므로, 개발자는 자체 언어 모델을 구축하고 호스팅하지 않아도 AI가 생성한 응답을 애플리케이션에 통합할 수 있습니다.

Chat Completions API는 요청과 응답 방식으로 작동합니다. 애플리케이션은 모델 식별자와 메시지 목록이 포함된 요청을 API 엔드포인트로 보냅니다. 선택한 모델은 입력을 처리하고 생성된 응답을 반환합니다.

기본 워크플로는 다음 단계로 구성됩니다:

1. 대화 준비: 애플리케이션은 사용자의 입력을 수집해 메시지 목록으로 구성합니다. 문맥을 제공하기 위해 이전 대화 메시지를 포함할 수도 있습니다.

2. API 요청 전송: 애플리케이션은 선택한 모델과 메시지 목록을 포함하여 https://api.openai.com/v1/chat/completions에 POST 요청을 보냅니다. 요청에는 Authorization: Bearer <API_KEY> 헤더가 사용됩니다. Python SDK의 client.chat.completions.create() 메서드는 이 요청 구조와 인증을 처리합니다.

3. 입력 처리: 모델은 메시지를 해석하고 각 메시지의 역할과 내용을 고려하여 제공된 문맥 및 파라미터에 따라 응답을 생성합니다.

4. 응답 수신: 스트리밍하지 않는 요청은 생성된 완료와 메타데이터가 포함된 JSON 응답을 반환합니다. 스트리밍을 활성화하면 API는 서버 전송 이벤트(SSE) 시퀀스를 보내며, 애플리케이션은 이벤트가 도착하는 대로 처리합니다.

5. 출력 표시 또는 처리: 애플리케이션은 생성된 메시지를 추출하여 사용자에게 표시하거나 다른 애플리케이션 구성 요소로 전달합니다.

이 워크플로는 OpenAI Chat Completions API의 요청 및 응답 모델을 기반으로 합니다.

Chat Completions API를 효과적으로 사용하려면 개발자는 주요 요청 파라미터와 이것이 모델 동작에 미치는 영향을 이해해야 합니다.

model 파라미터는 요청을 처리할 언어 모델을 지정합니다. 모델마다 제공하는 기능, 응답 속도, 추론 성능, 가격이 다를 수 있습니다.

개발자는 작업의 복잡성, 예상 응답 품질, 지연 시간 요구 사항, 예산에 따라 모델을 선택해야 합니다.

messages 파라미터에는 대화 메시지 배열이 포함됩니다. 각 메시지에는 일반적으로 role 및 content 필드가 포함됩니다.

일반적인 역할은 다음과 같습니다:

모델이 지원하는 지시 역할을 선택하세요. 동일한 지시에 대해 system 메시지와 developer 메시지를 모두 보낼 필요는 없습니다. 여러 턴에 걸쳐 문맥을 유지하려면 각 요청에 관련 대화 기록을 포함하세요. 호환되는 제공업체마다 지원하는 역할이 다를 수 있으므로, 통합을 조정할 때는 해당 모델의 자체 문서를 따르세요.

지원되는 모델 및 구성에서 temperature는 샘플링의 무작위성을 제어합니다. API 참조 문서는 범위를 0~2, 기본값을 1로 정의합니다. 사용자 지정 값을 설정하기 전에 선택한 모델이 해당 파라미터를 지원하는지 확인하세요.

• 낮은 온도: 더 집중적이고 예측 가능한 응답을 생성하므로 분류, 정보 추출, 구조화된 작업에 유용합니다.

• 높은 온도: 생성된 텍스트의 변화를 더 폭넓게 허용하므로 브레인스토밍과 창작 글쓰기에 유용할 수 있습니다.

일부 추론 구성에서는 사용자 지정 temperature 또는 top_p 값을 허용하지 않습니다. 이러한 구성에서는 해당 샘플링 파라미터를 생략하고 추론 노력이나 출력 제한과 같이 지원되는 제어 기능을 대신 사용하세요.

지원되는 경우 top_p는 뉴클리어스 샘플링을 통해 token 선택을 제어합니다. 후보 token을 선택하는 데 사용되는 누적 확률 임곗값을 설정합니다.

예를 들어 값이 0.1이면 모델은 누적 확률 질량이 가장 높은 10% 범위 내의 token을 고려합니다. 일반적으로 값이 낮을수록 출력이 더 집중되고, 값이 높을수록 더 다양한 결과가 생성됩니다.

OpenAI는 temperature와 top_p를 동시에 변경하기보다 둘 중 하나만 조정할 것을 권장합니다.

max_completion_tokens 파라미터는 해당하는 경우 추론 token을 포함하여 모델이 응답에서 생성할 수 있는 최대 token 수를 설정합니다.

적절한 제한을 설정하면 개발자가 출력 길이를 제어하고 token 소비량을 관리하는 데 도움이 됩니다. 모델이 응답을 완료하기 전에 이 제한에 도달하면 완료가 length 종료 사유로 끝날 수 있습니다.

stream 파라미터는 API가 생성된 응답을 한 번에 반환할지, 생성되는 대로 점진적으로 반환할지를 결정합니다.

• false: 생성이 완료된 후 전체 응답을 반환합니다.

• true: 서버 전송 이벤트(SSE)를 통해 응답 데이터를 애플리케이션으로 스트리밍합니다.

스트리밍은 전체 출력이 완료될 때까지 기다리는 대신 응답이 점진적으로 표시되는 것이 유용한 채팅 인터페이스와 애플리케이션에 적합합니다.

response_format 매개변수는 지원되는 모델에서 출력 형식을 선택합니다. 기본값은 텍스트입니다. type을 json_object로 설정하면 유효한 JSON을 생성하지만 특정 스키마를 강제하지 않는 JSON 모드가 활성화됩니다. 메시지에 JSON을 반환하라는 지침을 포함하세요.

예측 가능한 필드와 데이터 유형이 필요하다면 호환되는 모델에서 type: "json_schema" 및 strict: true를 사용한 JSON Schema 기반 구조화된 출력을 사용하세요. 엄격 모드에서는 JSON Schema의 지원되는 하위 집합만 사용할 수 있습니다. 결과를 처리하기 전에 거부 응답 또는 잘린 응답인지 확인하세요. 구성 세부 정보는 구조화된 출력 가이드를 참조하세요.

tool_choice 매개변수는 모델이 Chat Completions를 통한 도구 호출을 지원할 때 도구 선택을 제어합니다. 지원 여부는 모델과 추론 구성 모두에 따라 달라지며, 일부 최신 모델은 도구 사용을 위해 Responses API가 필요합니다. 요청에 도구를 추가하기 전에 이러한 요구 사항을 확인하세요.

일반적인 설정은 다음과 같습니다.

• none: 모델이 도구를 호출하지 못하도록 합니다.

• auto: 모델이 사용 가능한 도구를 호출할지 결정하도록 합니다.

• required: 모델이 하나 이상의 도구를 호출하도록 요구합니다.

이 기능은 함수 호출을 지원하여 애플리케이션이 모델이 생성한 결정을 외부 함수, 데이터베이스 및 서비스와 연결할 수 있게 합니다. 요청된 함수를 실행하고 그 결과를 모델에 반환하는 책임은 애플리케이션에 있습니다.

매개변수 정의와 모델 호환성 요구 사항은 Chat Completions API 레퍼런스를 참조하세요. 아래 Python 예제는 도구 없이 기본 텍스트 요청을 사용합니다.

개발자는 HTTP 요청 또는 공식 SDK를 통해 Chat Completions API에 액세스할 수 있습니다. 다음 예제에서는 Python으로 대화형 요청을 전송하고 생성된 응답을 가져옵니다.

1단계. API 키 발급

OpenAI API 플랫폼에서 API 키를 만들고, 계정에 선택한 모델에 대한 액세스 권한과 충분한 API 크레딧 또는 청구 여력이 있는지 확인하세요. 키는 애플리케이션 소스 코드 대신 환경 변수에 저장하세요. macOS 또는 Linux에서는 다음을 실행합니다.

YOUR_API_KEY를 본인의 키로 바꾸세요. Windows에서는 셸 또는 시스템 환경에 동일한 OPENAI_API_KEY 변수를 설정하세요.

2단계. OpenAI Python SDK 설치

pip를 사용하여 공식 Python 라이브러리를 설치합니다.

3단계. API 클라이언트 초기화

SDK를 가져오고 클라이언트를 초기화합니다. OpenAI()는 1단계에서 설정한 OPENAI_API_KEY 환경 변수를 자동으로 읽습니다.

4단계. 채팅 완료 요청 전송

모델과 메시지 목록을 지정하여 client.chat.completions.create()를 호출합니다. 이 예제에서는 낮은 추론 노력과 총 생성 한도 4,096 token으로 gpt-6-astra를 사용합니다. 계정에서 이 모델을 사용할 수 없다면 Chat Completions를 지원하는 모델을 선택하고 해당 문서에 맞게 매개변수를 조정하세요.

이 예제에서:

• model은 응답 생성에 사용되는 언어 모델을 지정합니다.

• messages는 지침과 사용자 입력을 제공합니다.

• reasoning_effort는 이 매개변수를 지원하는 모델의 추론 노력을 설정합니다.

• max_completion_tokens는 추론 token을 포함한 생성 token 수에 상한을 둡니다. 표시되는 텍스트의 특정 분량을 보장하지는 않습니다.

• response.choices[0].message.content는 어시스턴트의 응답을 추출합니다.

API 응답 처리

이 비스트리밍 요청에서 API는 완료 결과와 요청 메타데이터가 포함된 JSON을 반환합니다. Python SDK는 이를 ChatCompletion 객체로 파싱하므로, 예시에서는 response.choices[0].message.content처럼 속성을 통해 필드에 접근합니다.

주요 응답 필드는 다음과 같습니다.

finish_reason 필드는 생성이 어떻게 종료되었는지 개발자가 파악하는 데 도움이 됩니다. 일반적인 값으로는 stop, length, tool_calls가 있습니다.

개발자는 usage 필드를 확인하여 입력 및 출력 token 사용량을 모니터링할 수도 있습니다. 이는 API 비용을 추정하고 애플리케이션 사용을 최적화하는 데 유용합니다.

이 예시는 기본적인 텍스트 응답을 보여 줍니다. 스트리밍, 구조화된 출력 또는 도구를 추가할 때는 선택한 모델과 엔드포인트에 맞게 요청 및 응답 처리 로직을 모두 업데이트하세요.

OpenAI Chat Completions API의 대안을 찾는 개발자를 위해 Kimi API는 OpenAI 호환 API 형식을 통해 Moonshot AI의 대규모 언어 모델에 대한 액세스를 제공합니다.

Kimi는 Chat Completions, Responses, Messages 인터페이스를 제공합니다. 아래 예시에서는 앞서 소개한 SDK 워크플로를 재사용할 수 있도록 OpenAI 호환 Chat Completions 엔드포인트를 사용합니다. Kimi API 키를 구성하고 Kimi 기본 URL을 설정한 다음, 지원되는 모델을 선택하세요. 모델 매개변수, 메시지 역할 및 도구 지원에 대해서는 Kimi 자체 문서를 따르세요.

1단계. Kimi API 키 받기

Kimi API platform에 등록하고 개발자 콘솔에서 API 키를 생성하세요. 첫 요청을 보내기 전에 잔액, 모델 액세스 권한 및 계정 요청 제한을 확인하세요.

Kimi 키는 별도의 환경 변수에 저장하세요. macOS 또는 Linux에서는 다음을 실행합니다.

YOUR_KIMI_API_KEY를 본인의 Kimi 키로 바꾸세요. Windows에서는 환경 변수에 동일한 KIMI_API_KEY 변수를 설정하세요.

2단계. OpenAI Python SDK 설치

SDK가 아직 설치되지 않았다면 다음을 실행하세요.

3단계. Kimi API 클라이언트 구성

Kimi 기본 URL과 1단계에서 설정한 KIMI_API_KEY 변수를 사용해 별도의 kimi_client를 만드세요. os.environ으로 키를 읽으면 환경 변수가 누락된 경우 즉시 오류로 확인할 수 있습니다.

4단계. Chat Completions 요청 보내기

Kimi 클라이언트에서 동일한 SDK 메서드를 사용하세요. 이 요청은 kimi-k3를 선택하고, 지침에 Kimi가 지원하는 system 역할을 사용하며, 비스트리밍 텍스트 응답을 반환합니다.

• 작업 유형별 모델 옵션: Kimi K3.1 Pro는 복잡한 추론, 장기 코딩 및 지식 작업을 지원합니다. Highspeed 변형은 동일한 모델 기능을 더 빠른 출력 속도로 제공합니다. 위 예시에서는 Kimi K3를 사용합니다. 제공 여부와 마이그레이션 지침은 현재 모델 목록에서 확인하세요.

• OpenAI API 호환성: OpenAI Chat Completions 형식에 익숙한 개발자는 Kimi 모델을 통합할 때 유사한 요청 구조와 지원되는 SDK 워크플로를 재사용할 수 있습니다.

• 다중 턴 대화: 개발자는 메시지 기록을 제공하여 문맥을 인식하는 대화, 가상 비서 및 대화형 애플리케이션을 지원할 수 있습니다.

• 스트리밍 및 함수 호출: API는 스트리밍 응답과 도구 호출 워크플로를 지원하므로, 개발자는 더 상호작용적인 애플리케이션을 구축하고 모델을 외부 함수와 연결할 수 있습니다.

• 멀티모달 입력: 지원되는 Kimi 모델은 모델의 기능에 따라 텍스트, 이미지, 동영상 등 다양한 입력 유형을 처리할 수 있습니다.

Chat Completions API를 사용할 때 개발자는 인증, API 구성, 모델 제공 여부 또는 요청 제한과 관련된 오류를 겪을 수 있습니다. 이러한 일반적인 문제를 이해하면 원인을 파악하고 통합을 원활하게 실행하는 데 도움이 됩니다.

• 잘못되었거나 누락된 API 키: API 키가 잘못되었거나 만료, 폐기되었거나 올바르게 구성되지 않은 경우 HTTP 401과 같은 인증 오류가 발생할 수 있습니다. 키가 유효한지, 환경 변수가 올바르게 로드되었는지, 요청에 적절한 인증 자격 증명이 포함되어 있는지 확인하세요.

• 잘못된 API 기본 URL: 잘못된 엔드포인트로 전송된 요청은 404나 연결 실패 같은 오류를 반환할 수 있습니다. 기본 URL이 API 제공업체의 문서와 일치하는지, 요청에서 올바른 엔드포인트 경로를 사용하는지 확인하세요. OpenAI와 호환 제공업체 간에 전환할 때는 기본 URL도 그에 맞게 업데이트해야 합니다.

• 잘못되었거나 사용할 수 없는 모델 ID: 지정한 모델 이름이 잘못되었거나 계정에서 사용할 수 없거나 선택한 엔드포인트에서 지원되지 않으면 요청이 실패할 수 있습니다. 제공업체의 모델 문서를 확인하고 모델 ID가 API 계정에서 사용할 수 있는 ID와 일치하는지 확인하세요.

• 컨텍스트 길이 초과: 입력 메시지와 생성된 출력의 합이 모델의 컨텍스트 창을 초과하면 API가 요청을 거부할 수 있습니다. 입력 길이를 줄이거나, 불필요한 대화 기록을 삭제하거나, 이전 메시지를 요약한 뒤 다시 요청을 보내세요.

• 출력 잘림: 응답이 max_completion_tokens 제한에 도달하면 요청한 콘텐츠가 완료되기 전에 중단될 수 있습니다. 지원되는 경우 token 제한을 늘리거나, 긴 생성 작업을 더 작은 요청으로 나누세요. choices[].finish_reason를 확인하여 응답이 length 제한 때문에 종료되었는지도 확인할 수 있습니다.

• 속도 제한 또는 할당량 초과: OpenAI에서 HTTP 429는 요청 또는 token 속도 제한, 지출 한도 또는 기타 사용 제한을 나타낼 수 있습니다. 재시도하기 전에 오류 유형과 코드를 확인하세요. 일시적인 속도 제한인 경우 요청 빈도를 줄이고, 제공되는 경우 Retry-After를 따르거나 지수 백오프를 사용하세요.

오류가 크레딧 소진, 결제 한도 또는 지출 한도를 나타내는 경우 계정 잔액과 결제 설정을 확인하세요. 반복해서 재시도해도 액세스 권한은 복구되지 않습니다. Kimi 또는 다른 호환 제공업체를 사용하는 경우 상태 코드와 할당량 규칙이 다를 수 있으므로 해당 제공업체의 오류 코드 문서를 따르세요.

더 효율적으로 디버깅하려면 요청 매개변수를 변경하기 전에 API가 반환한 HTTP 상태 코드와 오류 메시지를 확인하세요. 이러한 정보는 인증 문제, 구성 오류, 사용 제한을 구분하는 데 도움이 됩니다.

Chat Completions API는 다양한 애플리케이션 시나리오를 지원할 수 있습니다. 구조화된 메시지 형식과 맞춤 설정 가능한 생성 매개변수 덕분에 간단한 텍스트 기반 기능부터 더 복잡한 AI 워크플로까지 폭넓게 활용할 수 있습니다.

• AI 챗봇 및 가상 비서: 개발자는 API를 사용해 웹사이트, 모바일 애플리케이션, 고객 서비스 플랫폼용 대화형 비서를 구축할 수 있습니다. 이전 메시지를 후속 요청에 전달하면 애플리케이션은 대화 맥락을 유지하고 더 관련성 높은 응답을 제공할 수 있습니다.

• 콘텐츠 제작 및 텍스트 편집: API는 사용자 지시에 따라 텍스트를 생성하고 변환할 수 있습니다. 애플리케이션은 이를 활용해 블로그 게시물 초안을 작성하고, 마케팅 문구를 쓰고, 긴 콘텐츠를 요약하고, 문단을 다시 쓰고, 대상과 목적에 맞게 문체를 조정할 수 있습니다.

• 텍스트 분류 및 정보 추출: 기업은 대량의 텍스트를 처리하는 워크플로에 API를 통합할 수 있습니다. 예를 들어 고객 피드백을 분류하고, 감정을 식별하고, 메시지에서 중요한 정보를 추출하고, 비정형 콘텐츠를 미리 정의된 범주로 정리할 수 있습니다.

• 코딩 지원 도구: API는 코드를 생성하고, 프로그래밍 개념을 설명하고, 해결책을 제안하고, 개발자가 오류를 식별하도록 도와 소프트웨어 개발 도구를 지원할 수 있습니다. 애플리케이션은 함수 호출을 통해 모델을 외부 개발 도구에 연결할 수도 있습니다.

• AI 기반 비즈니스 워크플로: 개발자는 반복적인 언어 관련 작업을 자동화하기 위해 API를 비즈니스 애플리케이션에 도입할 수 있습니다. 고객 문의 처리, 보고서 생성, 문서에서의 정보 추출, 미리 정의된 지침에 따른 응답 준비 등이 그 예입니다.

OpenAI Chat Completions API는 개발자가 대화형 AI를 애플리케이션에 도입하고 더 유용한 사용자 경험을 만들 수 있는 실용적인 방법을 제공합니다. 적절한 모델을 선택하고, 매개변수를 이해하며, API 응답을 신중하게 처리하면 애플리케이션 성능에 실질적인 차이를 만들 수 있습니다. 하지만 개발자가 AI 기반 솔루션을 구축할 때 하나의 제공업체에만 의존할 필요는 없습니다. 다른 선택지를 살펴보고 싶다면 Kimi API를 사용해 보고, OpenAI 호환 설정이 개발 요구 사항에 어떻게 맞는지 확인해 보세요.