Chat Completion API: 작동 방식과 사용 방법

Chat Completion API의 작동 방식을 살펴보고 Python과의 통합 방법을 알아보세요. 주요 매개변수, 스트리밍, 도구 호출을 이해하고, Kimi API와 같은 OpenAI 호환 제공업체가 유연한 AI 애플리케이션 개발을 어떻게 지원하는지 확인할 수 있습니다.

9분 읽기업데이트: 2026-11-14
Kimi API 사용해 보기
Chat Completion API 요청 및 응답 흐름

AI 챗봇을 구축하든 애플리케이션에 대화 기능을 추가하든, AI가 대화를 처리하는 방식을 이해하는 일은 중요합니다. Chat Completion API는 애플리케이션을 AI 모델과 연결해 관련성 높고 사람 같은 응답을 생성할 수 있게 합니다. Python 통합, 스트리밍, 도구 호출 등의 기능을 활용하면 개발자는 더욱 상호작용적인 애플리케이션을 구축할 수 있습니다. 작동 방식과 사용 방법, 그리고 Kimi API와 같은 제공업체가 유연한 AI 개발을 어떻게 지원하는지 살펴보겠습니다.

Chat Completions API란 무엇인가요?

Chat Completions API는 애플리케이션이 일련의 메시지를 AI 모델에 전송하고 어시스턴트 응답을 받을 수 있게 하는 인터페이스로, 단일 턴과 다중 턴 대화를 모두 지원합니다. 예를 들어 Kimi K3.1 Pro를 사용해 Python 데코레이터에 관한 질문에 답한 뒤 후속 질문을 할 수 있습니다.

  • 첫 번째 요청: 사용자 메시지 "Python 데코레이터란 무엇인가요?"를 전송합니다. Kimi는 개념을 설명하는 어시스턴트 메시지를 반환합니다.

  • 두 번째 요청: 대화를 계속하려면 이전 사용자 메시지, Kimi의 전체 어시스턴트 메시지, 그리고 새 사용자 메시지 "예를 들어 주실 수 있나요?"를 전송합니다.

messages 배열에는 각 요청에 필요한 컨텍스트가 담깁니다. 다음 세 가지 핵심 설계 결정 덕분에 이 인터페이스는 널리 채택되었습니다.

  • 애플리케이션이 관리하는 기록: 애플리케이션이 대화 기록을 관리하고 각 요청에 관련 컨텍스트를 포함하므로, 개발자는 모델에 표시할 내용을 제어할 수 있습니다.

  • 일반적인 메시지 역할: 일반적인 역할로는 system(지침), user(입력), assistant(모델 출력, 다중 턴 컨텍스트를 위해 다시 전달됨), tool(함수 호출 결과)이 있습니다. 이러한 역할을 함께 사용하면 지침, 대화, 도구 상호작용을 표현할 수 있습니다.

  • 유연한 기능: 모델 지원 여부에 따라 이 인터페이스는 스트리밍, 도구 호출, 시각적 입력, 구조화된 출력을 처리할 수 있습니다. Kimi K3.1 Pro는 이러한 기능을 지원합니다.

Kimi에서 Chat Completions API 사용하기

다음 예제에서는 Kimi K3.1 Pro와 OpenAI Python SDK를 사용해 클라이언트 구성, 요청 전송, 응답 처리, 도구 호출 구현 방법을 보여줍니다.

빠른 시작: OpenAI Python SDK로 Kimi 호출하기

OpenAI Python SDK를 설치합니다:

pip install --upgrade openai

Kimi API 키를 환경 변수로 설정합니다:

export MOONSHOT_API_KEY="sk-your-kimi-key"

OpenAI API 키는 필요하지 않습니다. OpenAI Python SDK는 클라이언트 라이브러리로 사용되며, Kimi API 키와 기본 URL이 요청을 인증하고 Kimi로 라우팅합니다.

클라이언트를 초기화하고 첫 번째 요청을 전송합니다:

import os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1", ) resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ {"role": "user", "content": "Explain REST in one paragraph."} ], ) print(resp.choices[0].message.content)

이 예제에서는 Kimi의 국제 API 엔드포인트를 사용합니다. 공식 설정 및 모델 세부 정보는 Kimi K3.1 Pro Quickstart를 참조하세요.

주요 매개변수

이 매개변수는 Chat Completions API를 통해 Kimi K3.1 Pro를 호출할 때 사용할 수 있는 주요 옵션을 다룹니다.

매개변수용도
modelkimi-k3.1-pro과 같은 모델 ID를 지정합니다.
messages이전 사용자 입력과 어시스턴트 응답을 포함한 대화 메시지를 제공합니다. 텍스트 및 멀티모달 콘텐츠를 지원합니다.
reasoning_effort추론 깊이를 제어합니다. low, high, max(기본값)를 사용할 수 있습니다.
max_completion_tokens추론 token과 최종 답변 token을 모두 포함한 최대 생성 예산을 설정합니다. 입력 token은 별도로 계산되지만, 입력 token과 생성 token의 합계는 모델의 컨텍스트 윈도 내에 들어와야 합니다.
stream완성된 출력을 기다리지 않고 응답을 점진적으로 받으려면 true로 설정합니다.
tools모델이 애플리케이션에 실행을 요청할 수 있는 함수를 정의합니다.
response_format출력 형식을 제어합니다. JSON 모드의 json_object와 스키마로 제한된 구조화 출력을 위한 json_schema를 지원합니다.

참고: Kimi K3.1 Pro는 고정된 샘플링 설정을 사용합니다. 요청에 temperature 또는 top_p를 추가하지 마세요. 매개변수 세부 정보와 지원되는 값은 Chat Completions API reference를 참조하세요.

응답 읽기

요청이 성공하면 반환된 completion 객체를 통해 주요 응답 필드에 접근할 수 있습니다.

  • choices[0].message – 모델이 함수를 요청할 때의 content 또는 tool_calls를 포함한 어시스턴트의 응답이 담깁니다.

  • choices[0].finish_reason – stop, length, tool_calls 등 생성이 중지된 이유를 나타냅니다.

  • usage – 사용 가능한 경우 입력, 출력, 캐시된 token 수를 포함한 token 사용량 정보를 제공합니다.

기본 텍스트 응답은 choices[0].message.content에서 읽습니다. 모델이 tool_calls를 반환하면 애플리케이션은 요청된 함수를 실행하고 후속 요청에서 결과를 제출해야 합니다.

스트리밍 예제

stream=True로 설정하면 Kimi의 응답을 점진적인 청크 단위로 받을 수 있습니다. 다음 예제에서는 앞서 구성한 client를 재사용하고, 최종 답변이 도착하는 대로 출력합니다:

stream = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ {"role": "user", "content": "Write a haiku about autumn."} ], stream=True, ) for chunk in stream: if not chunk.choices: continue delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True)

Kimi K3.1 Pro는 추론 콘텐츠를 최종 답변과 별도로 반환합니다. 이 예제는 delta.content만 출력하므로, 별도의 reasoning_content 필드를 처리하지 않고 최종 응답을 표시합니다.

도구 호출 개요

도구 호출을 사용하면 작업에 모델 자체의 응답을 넘어서는 정보나 작업이 필요할 때 Kimi가 외부 함수를 요청할 수 있습니다. 예를 들어 사용자가 "오늘 도쿄에 우산을 가져가야 할까요?"라고 묻는 경우, Kimi는 예보를 조회하기 위해 get_weather 함수를 요청할 수 있습니다.

워크플로는 세 단계로 이루어집니다:

  1. 함수 선언: tools 매개변수에서 get_weather와 예상 인수를 정의합니다.

  2. 도구 실행: Kimi는 함수 이름과 인수가 포함된 tool_calls 항목을 반환합니다. 애플리케이션이 해당 함수를 실행하고 날씨 데이터를 가져옵니다.

  3. 결과 다시 전송: Kimi의 전체 어시스턴트 메시지와 도구 결과(일치하는 tool_call_id 사용)를 대화에 추가한 다음, 사용자에게 보여 줄 답변을 생성하도록 Kimi를 다시 호출합니다.

다음 예제에서는 앞서 구성한 client를 재사용합니다. 실행하기 전에 JSON으로 직렬화할 수 있는 날씨 데이터를 반환하는 get_weather(city) 함수를 구현했는지 확인하세요. 이 함수는 Kimi가 아니라 애플리케이션에서 실행됩니다.

import json tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get the weather forecast for a city.", "parameters": { "type": "object", "properties": { "city": {"type": "string"} }, "required": ["city"] } } } ] messages = [ {"role": "user", "content": "Should I bring an umbrella in Tokyo today?"} ] # Ask Kimi whether it needs to call a tool resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=messages, tools=tools, ) assistant_message = resp.choices[0].message # Preserve the complete assistant message, including tool_calls messages.append(assistant_message) # Execute the requested function in your application for tool_call in assistant_message.tool_calls or []: if tool_call.function.name == "get_weather": args = json.loads(tool_call.function.arguments) # Call your own weather service or API weather_result = get_weather(city=args["city"]) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(weather_result) }) # Let Kimi interpret the tool result and answer the user final_resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=messages, tools=tools, ) print(final_resp.choices[0].message.content)

여기서 get_weather()는 Kimi가 직접 실행하는 함수가 아니라 애플리케이션에서 구현한 함수를 나타냅니다. Kimi는 언제 이를 요청할지 결정하고 인수를 제공하며, 실제 작업을 수행하고 결과를 반환하는 것은 애플리케이션입니다.

프로덕션 환경에서는 각 도구 호출을 처리하고, 해당 결과를 대화에 추가한 뒤, 업데이트된 메시지를 Kimi에 다시 전송하는 루프를 구현하세요. 모델이 추가 도구를 요청하지 않고 최종 답변을 반환할 때까지 이 과정을 반복합니다.

제공업체 선택 시 "OpenAI 호환"이 중요한 이유

많은 제공업체가 OpenAI Chat Completions 형식을 지원하므로 개발자는 익숙한 SDK와 요청 구조를 재사용할 수 있습니다. 일반적으로 전환하려면 기본 URL, API 키, 모델 ID를 업데이트하고 지원되는 매개변수와 응답 처리 방식을 확인하면 됩니다. 제공업체를 비교할 때는 다음 요소를 고려하세요:

  1. 호환성 충실도: 스트리밍, 도구 호출, 구조화된 출력, usage 보고가 애플리케이션의 기대대로 작동하는지 확인하세요. 같은 API 형식과 호환된다고 해서 제공업체마다 기능 지원이나 응답 동작이 동일하다는 보장은 없습니다.

  2. 워크로드에 맞는 모델 품질: 일반적인 벤치마크보다 사용하는 언어의 구성과 작업 유형이 더 중요합니다.

  3. 컨텍스트 윈도우: 긴 컨텍스트 모델은 한 번의 요청으로 더 많은 소스 자료를 처리하여 일부 문서 워크플로를 단순화할 수 있습니다.

  4. 비용 구조: 캐싱과 배치 할인은 명목상의 token당 가격보다 더 큰 영향을 미치는 경우가 많습니다.

  5. 생태계 범위: Responses 및 Anthropic Messages와 같은 추가 호환 엔드포인트는 애플리케이션이 발전함에 따라 더 많은 통합 옵션과 유연성을 제공할 수 있습니다.

Kimi API: 주목할 만한 OpenAI 호환 제공업체

Moonshot AI가 개발한 Kimi API는 OpenAI 호환 제공업체를 찾고 있다면, 특히 중국어 애플리케이션, 장문서 처리, 코딩 에이전트 용도로 고려할 만합니다. 익숙한 API 통합 방식에 Kimi의 긴 컨텍스트 및 추론 기능을 결합합니다.

바로 적용 가능한 호환성

애플리케이션에서 이미 OpenAI Python SDK를 사용하고 있다면 전체 요청 워크플로를 다시 작성하지 않고도 Kimi를 통합할 수 있습니다. 익숙한 Chat Completions 인터페이스는 그대로 유지하면서 base_url, api_key, 모델 ID를 포함한 API 구성만 업데이트하면 됩니다.

예를 들어 다음 코드는 report.txt에서 로컬 보고서를 읽고, 그 내용을 요약하도록 Kimi K3.1 Pro에 전송한 뒤 생성된 응답을 스트리밍합니다:

from pathlib import Path report_text = Path("report.txt").read_text(encoding="utf-8") resp = client.chat.completions.create( model="kimi-k3.1-pro", messages=[ { "role": "user", "content": f"Summarize the following report:\n\n{report_text}" } ], stream=True, ) for chunk in resp: if not chunk.choices: continue content = chunk.choices[0].delta.content if content: print(content, end="", flush=True)

여기서 client는 환경 변수에서 읽은 API 키로 앞서 초기화한 Kimi 클라이언트를 재사용합니다. 지역에 따라 기본 URL을 선택하세요. 국제 플랫폼은 https://api.moonshot.ai/v1을, 중국 본토에서 API에 접속하는 사용자는 https://api.moonshot.cn/v1을 사용합니다.

이 방식을 사용하면 기존 OpenAI SDK 워크플로를 유지하면서 문서 요약 및 기타 API 기반 애플리케이션 작업에 Kimi 모델을 사용할 수 있습니다.

Kimi의 차별점

  • 100만 token 컨텍스트 윈도우를 갖춘 플래그십 모델: Kimi K3.1 Pro는 최대 100만 token의 컨텍스트 윈도우와 네이티브 시각 이해 기능을 지원합니다. 개발자는 방대한 코드베이스, 책 한 권 분량의 문서, 이미지 입력을 하나의 워크플로에서 다룰 수 있어 복잡한 추론, 코딩, 멀티모달 애플리케이션에 적합합니다.

  • 유연한 비용 최적화: Kimi API는 반복되는 요청 접두사에 대한 자동 컨텍스트 캐싱과 실시간 응답이 필요하지 않은 대규모 작업을 위한 Batch API 추론을 지원합니다. 캐시 요금과 Batch 가격은 모델 및 적용되는 요금 규칙에 따라 달라집니다. 최신 요금 및 청구 세부 정보는 공식 Kimi API 요금에서 확인하세요.

  • API 생태계 전반의 호환성: Kimi는 OpenAI 호환 Chat Completions 및 Responses API 엔드포인트와 Anthropic Messages 호환 엔드포인트를 제공합니다. 개발자는 엔드포인트와 지원 기능에 맞게 조정하여 익숙한 SDK와 API 형식으로 기존 워크플로에 Kimi K3.1 Pro를 통합할 수 있습니다.

결론

Chat Completions API는 쉽게 시작할 수 있습니다. API 자격 증명을 설정하고 요청을 보낸 뒤 choices[0].message.content에서 생성된 응답을 읽으면 됩니다. 첫 API 호출이 작동하면 멀티턴 대화, 스트리밍 응답 또는 도구 호출을 추가해 애플리케이션의 요구에 맞춰 통합을 확장할 수 있습니다. Kimi로 개발할 준비가 되셨나요? Kimi API 키를 발급받아 API 요청을 시작하세요.

Kimi API 사용해 보기

자주 묻는 질문

아니요. Chat Completions API는 OpenAI 모델만을 위한 API가 아닙니다. Kimi를 비롯한 다른 AI 제공업체도 OpenAI 호환 Chat Completions 형식을 따르는 API를 제공합니다. 따라서 개발자는 기능 지원에 차이가 있을 수 있지만, 여러 제공업체가 지원하는 모델에 익숙한 SDK와 요청 구조를 재사용할 수 있습니다.
두 API 모두 애플리케이션이 AI 모델과 상호작용할 수 있도록 하지만, 요청 및 응답 구조는 서로 다릅니다. Chat Completions는 messages 배열을 사용하고 choices 배열을 통해 응답을 반환합니다. Responses API는 다양한 콘텐츠 유형과 도구 상호작용을 지원하는 더 유연한 입력 및 출력 구조를 사용합니다. 대화 상태 관리 방식은 제공업체마다 다릅니다. Kimi의 Responses API에서는 응답 ID 연결에 의존하지 말고 각 요청에 관련 대화 기록을 포함해야 합니다.
애플리케이션에서 OpenAI SDK를 사용한다면 일반적으로 세 가지 구성 값만 변경해 Kimi로 전환할 수 있습니다. base_url을 Kimi의 API 엔드포인트로, api_key를 Kimi API 키로, model을 지원되는 Kimi 모델 ID로 업데이트하면 됩니다. 그런 다음 스트리밍 및 도구 호출처럼 애플리케이션이 사용하는 매개변수와 기능이 지원되는지 확인하기 위해 통합을 테스트하세요.
다음도 마음에 드실 수 있습니다
OpenAI Chat Completions API: 종합 가이드
OpenAI Chat Completions API: 종합 가이드
2026-11-14
AI 개발을 위한 무료 및 유료 LLM API 10선
AI 개발을 위한 무료 및 유료 LLM API 10선
2026-11-14
LLM API 가이드: 기능, 이점 및 주요 활용 사례
LLM API 가이드: 기능, 이점 및 주요 활용 사례
2026-11-14
모델 API: Kimi API 개발자 가이드
모델 API: Kimi API 개발자 가이드
2026-11-14
OpenAI 호환 API: 개발자를 위한 실용 가이드
OpenAI 호환 API: 개발자를 위한 실용 가이드
2026-11-14