Chat Completions API
가장 범용적인 텍스트 생성 엔드포인트입니다.
OpenAI, Anthropic, Google Gemini, xAI 등 대부분의 모델을 이 하나의 엔드포인트로 사용할 수 있으며, OpenAI SDK와 100% 호환됩니다. 기존 OpenAI 코드의 Base URL만 변경하면 바로 시작할 수 있습니다.
- 공식 레퍼런스: OpenAI Chat Completions API
이 엔드포인트는 텍스트 모델 전용입니다. 이미지 모델을
model로 지정하면 404 invalid_request_error - Model '<name>' not found가 반환됩니다 — 이미지는 /images/generate를 사용하세요.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 3.1 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+ 및 Gemini 계열. Gemini에서는 Google이 내부적으로 사고 토큰으로 환산합니다 (low ≈ 1,024 / medium ≈ 8,192 / high ≈ 24,576 토큰).thinking_budget
사고 토큰 예산. Gemini 계열에서만 사용합니다. 게이트웨이가 값을 integer
reasoning_effort로 환산해 전달합니다 — 1–2048은 low, 2049–16384는 medium, 16385 이상은 high. 0 또는 -1(자동)은 별도 지정 없이 모델 기본값으로 동작합니다.thinking_level
string
"minimal" / "low" / "medium" / "high" — Gemini 계열. minimal은 low로 처리됩니다.thinking_budget·thinking_level은 Gemini 계열 전용입니다. 다른 제공업체 모델에 보내면 변환 없이 그대로 전달되므로 사용하지 마세요. 두 파라미터를 함께 보내면 에러가 나지는 않고 thinking_level이 우선하며 thinking_budget은 무시됩니다.일부 모델에서
reasoning_effort와 tools를 동시에 사용하면 400 에러가 발생할 수 있습니다 (GPT-5.6 시리즈, chat 모델, Grok 4.6 등). 게이트웨이는 이 경우 자동으로 reasoning_effort를 제거하고 재시도하므로, 별도 처리 없이 안정적으로 사용할 수 있습니다.지원 제공업체
| 제공업체 | 예시 모델 |
|---|---|
| OpenAI | gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.5 |
| Anthropic | claude-opus-5, claude-sonnet-5, claude-fable-5, claude-haiku-4-5-20251001 |
| Google Gemini | gemini-3.1-pro-preview, gemini-3.7-flash, gemini-3.5-flash |
| xAI | grok-4.6, grok-4.5 |
| 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 예제 — 터미널에서 빠르게 테스트
- 에러 가이드 — 문제 발생 시 참고
마지막 수정 날짜: Aug 24, 2026