Chat Completions API
가장 범용적인 텍스트 생성 엔드포인트입니다.
OpenAI, Anthropic, Google Gemini, xAI 등 대부분의 모델을 이 하나의 엔드포인트로 사용할 수 있으며, OpenAI SDK와 100% 호환됩니다. 기존 OpenAI 코드의 Base URL만 변경하면 바로 시작할 수 있습니다.
- 공식 레퍼런스: OpenAI Chat Completions API
Chat Completions
POST
/v1/gateway/chat/completions/채팅 완성을 생성합니다. 게이트웨이는 OpenAI Chat API와 동일한 요청/응답 스키마를 구현합니다.
요청 헤더
파라미터
핵심
model
string
required
GET /v1/gateway/models/에서 확인 가능한 모델 이름.messages
대화 기록 (role + content).array
required
System / Developer message
모델이 따라야 하는 지침.object
role
string
required
"system" 또는 "developer"content
지침 내용string | array
required
User message
사용자 입력.object
role
string
required
"user"content
사용자 입력 내용string | array
required
Assistant message
모델이 생성한 응답.object
role
string
required
"assistant"content
생성된 응답string | array
required
stream
SSE 스트리밍 활성화 (기본값: boolean
false).stream_options
object
{"include_usage": true} — 마지막 스트림 청크에 사용량 포함.샘플링
temperature
무작위성 0–2. 낮을수록 더 결정적. 기본값: float
1.0.일부 OpenAI 모델(
gpt-5, gpt-5-mini, gpt-5.1-chat-latest, gpt-5.2-chat-latest)은 temperature: 1만 지원합니다. 다른 값을 설정하면 400 에러가 반환됩니다.top_p
핵 샘플링 임계값. 기본값: float
1.0.top_k
Top-k 샘플링 (Anthropic OpenAI 호환 전용).integer
출력 제한
max_tokens
최대 출력 토큰. 최신 모델에서는 integer
max_completion_tokens로 자동 변환됩니다.추론 모델(GPT-5 시리즈, Gemini 2.5 Pro)은 내부 추론 토큰이
max_tokens 예산에 포함됩니다. 너무 낮게 설정하면(예: 4096 미만) 빈 응답이 반환될 수 있습니다. 추론이 필요한 작업에는 최소 16000 이상 사용하세요.max_completion_tokens
직접 별칭; o-시리즈 / gpt-5+ 모델에 사용.integer
stop
최대 4개의 중단 시퀀스.string | array
도구 호출
tools
도구 정의 목록 (array
type: "function").tool_choice
string | object
"auto", "none", "required", 또는 {"type":"function","function":{"name":"..."}}.구조화된 출력
response_format
object
{"type": "json_schema", "json_schema": {"name": "...", "strict": true, "schema": {...}}}. strict: true와 additionalProperties: false가 포함된 유효한 JSON Schema가 필요합니다.추론 / 사고
reasoning_effort
string
"low" / "medium" / "high" — OpenAI o-시리즈 및 gpt-5+.thinking_budget
최대 사고 토큰 (0–8192, 또는 동적의 경우 integer
-1). Gemini 2.5 시리즈 전용.thinking_level
Gemini 3.0 시리즈 전용. Flash: string
"minimal"/"low"/"medium"/"high". Pro: "low"/"high".thinking_budget과 thinking_level은 상호 배타적입니다. 두 파라미터를 동시에 사용하면 에러가 발생할 수 있으니 주의해주세요.일부 모델에서
reasoning_effort와 tools를 동시에 사용하면 400 에러가 발생할 수 있습니다 (GPT-5.4 시리즈, chat 모델, Grok 4 등). 게이트웨이는 이 경우 자동으로 reasoning_effort를 제거하고 재시도하므로, 별도 처리 없이 안정적으로 사용할 수 있습니다.지원 제공업체
| 제공업체 | 예시 모델 |
|---|---|
| OpenAI | gpt-5.4, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5.1 |
| Anthropic | claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001 |
| Google Gemini | gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-2.5-pro |
| xAI | grok-4, grok-3 |
| Perplexity | sonar-pro, sonar-reasoning-pro |
| Meta / 오픈소스 | meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8 |
Anthropic 네이티브 기능(확장 사고, 프롬프트 캐싱, 비전)이 필요하신가요? Messages API를 사용하시면 모든 Anthropic 전용 기능을 그대로 사용할 수 있습니다.
코드 예제
기본 채팅 (Python)
스트리밍 (JavaScript)
다음 단계
- OpenAI SDK 연동 — Python/JavaScript에서 바로 사용해보세요
- curl 예제 — 터미널에서 빠르게 테스트
- 에러 가이드 — 문제 발생 시 참고
마지막 수정 날짜: Apr 09, 2026