> ## Documentation Index
> Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# GPT 전체 모델 인터페이스 - Chat Completions 전체 매개변수
> - GPT 시리즈 텍스트 모델용 OpenAI 호환 Chat Completions API이며, 구체적인 모델은 `model`로 선택합니다(지정 가능한 값 전체는 `model` 매개변수의 대조표 참고)
- 전 시리즈가 추론 모델이며 추론 깊이는 `reasoning_effort`로 제어합니다. 추론 token은 출력 token으로 청구됩니다
- Prompt 캐시가 자동으로 적용됩니다: 캐시에 적중한 입력 token은 더 저렴한 캐시 요금으로 청구됩니다
- 동기 모드와 스트리밍(SSE) 모드를 지원합니다
- 텍스트와 이미지 혼합 입력, 그리고 `function` 도구 호출을 지원합니다
- 서버 측 도구(웹 검색, 코드 실행, 문서 검색, MCP)는 [Responses API](../responses/responses-reference)에서만 제공됩니다
- **참고** 샘플링 계열 매개변수(`temperature`, `top_p`, `logprobs` 등)는 모델별로 지원 범위가 다르므로 아래 각 매개변수 설명을 확인하세요
**BaseURL**: 기본 BaseURL은 `https://direct.evolink.ai`이며, 텍스트 모델 지원이 더 우수하고 장시간 연결을 지원합니다. `https://api.evolink.ai`는 멀티모달 서비스의 주력 엔드포인트이며, 텍스트 모델에 대해서는 대체 주소로 사용됩니다.
**서버 측 도구**(웹 검색, 코드 실행, 문서 검색, MCP)는 [Responses API](../responses/responses-reference)에서만 제공됩니다. Chat Completions 엔드포인트는 일반 `function` 도구 호출만 지원합니다.
**참고** 본 시리즈는 전부 추론 모델입니다. `stop`(정지 시퀀스)과 `web_search_options`는 모든 모델에서 지원되지 않으며 전달하면 `400`이 반환됩니다. `logit_bias`는 본 시리즈 모델에 적용되지 않습니다.
`temperature`, `top_p`, `frequency_penalty`, `presence_penalty`, `logprobs`, `verbosity`는 모델별로 지원 범위가 다르므로 위의 각 매개변수 설명을 기준으로 하세요.
## OpenAPI
````yaml ko/api-manual/language-series/gpt/chat-completions/chat-completions-reference.json POST /v1/chat/completions
openapi: 3.1.0
info:
title: GPT 전체 모델 인터페이스 - Chat Completions 전체 매개변수
description: OpenAI 호환 Chat Completions API로 GPT 시리즈 텍스트 모델을 호출하기 위한 전체 매개변수 설명서입니다.
license:
name: MIT
version: 1.0.0
servers:
- url: https://direct.evolink.ai
description: 프로덕션 (권장)
- url: https://api.evolink.ai
description: 대체 URL
security:
- bearerAuth: []
tags:
- name: Chat Completions
description: OpenAI 호환 대화 완성 API
paths:
/v1/chat/completions:
post:
tags:
- Chat Completions
summary: GPT 대화 완성 (전체 모델, 전체 매개변수)
description: >-
- GPT 시리즈 텍스트 모델용 OpenAI 호환 Chat Completions API이며, 구체적인 모델은 `model`로
선택합니다(지정 가능한 값 전체는 `model` 매개변수의 대조표 참고)
- 전 시리즈가 추론 모델이며 추론 깊이는 `reasoning_effort`로 제어합니다. 추론 token은 출력 token으로
청구됩니다
- Prompt 캐시가 자동으로 적용됩니다: 캐시에 적중한 입력 token은 더 저렴한 캐시 요금으로 청구됩니다
- 동기 모드와 스트리밍(SSE) 모드를 지원합니다
- 텍스트와 이미지 혼합 입력, 그리고 `function` 도구 호출을 지원합니다
- 서버 측 도구(웹 검색, 코드 실행, 문서 검색, MCP)는 [Responses
API](../responses/responses-reference)에서만 제공됩니다
- **참고** 샘플링 계열 매개변수(`temperature`, `top_p`, `logprobs` 등)는 모델별로 지원 범위가
다르므로 아래 각 매개변수 설명을 확인하세요
operationId: gptChatCompletionsReference
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionRequest'
responses:
'200':
description: >-
대화 생성 성공(JSON 객체이며, `stream=true`인 경우 `data: [DONE]`으로 종료되는 SSE 이벤트
스트림)
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponse'
'400':
description: >-
요청 매개변수가 유효하지 않음(해당 모델이 지원하지 않는 매개변수 포함. 오류 메시지에 구체적인 매개변수 이름이
표시됩니다)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 400
message: >-
Unsupported parameter: 'stop' is not supported with this
model.
type: invalid_request_error
'401':
description: 인증되지 않음, 유효하지 않거나 만료된 토큰
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 401
message: Invalid or expired token
type: authentication_error
'402':
description: 할당량 부족
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 402
message: Insufficient quota
type: insufficient_quota_error
fallback_suggestion: https://evolink.ai/dashboard/billing
'429':
description: 요청 한도를 초과했습니다
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 429
message: Rate limit exceeded
type: rate_limit_error
fallback_suggestion: retry after 60 seconds
'500':
description: 서버 내부 오류
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 500
message: Internal server error
type: internal_server_error
fallback_suggestion: try again later
'503':
description: 서비스 일시적으로 사용 불가
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
code: 503
message: Service temporarily unavailable
type: service_unavailable_error
fallback_suggestion: retry after 30 seconds
components:
schemas:
ChatCompletionRequest:
type: object
required:
- model
- messages
properties:
model:
type: string
description: |-
호출할 모델:
| 모델 ID | 컨텍스트 윈도우 | 포지셔닝 |
|---|---|---|
| `gpt-5.6-sol` | 1,050,000 | GPT-5.6 제품군, 최첨단 추론 |
| `gpt-5.6-terra` | 1,050,000 | GPT-5.6 제품군, 균형 잡힌 프로덕션 |
| `gpt-5.6-luna` | 1,050,000 | GPT-5.6 제품군, 높은 처리량과 비용 관리 |
| `gpt-5.5` | 400,000 | 범용 추론 모델 |
| `gpt-5.4` | 128,000 | 범용 추론 모델 |
| `gpt-5.2` | 400,000 | 범용 추론 모델 |
| `gpt-5.1` | 400,000 | 범용 추론 모델 |
enum:
- gpt-5.6-sol
- gpt-5.6-terra
- gpt-5.6-luna
- gpt-5.5
- gpt-5.4
- gpt-5.2
- gpt-5.1
example: gpt-5.6-sol
messages:
type: array
description: >-
채팅 메시지 목록으로, 여러 턴의 컨텍스트와 멀티모달 입력을 지원합니다.
`role`에는 `system` / `developer` / `user` / `assistant` / `tool`을 지정할
수 있습니다.
`content`는 문자열이어도 되고 콘텐츠 블록 배열이어도 됩니다. 블록 유형은 `text`(텍스트)와
`image_url`(이미지) 두 가지를 지원합니다:
```json
"content": [
{ "type": "text", "text": "이 이미지에는 무엇이 있나요?" },
{
"type": "image_url",
"image_url": { "url": "https://example.com/photo.png", "detail": "auto" }
}
]
```
**이미지**
- `image_url.url`에 이미지의 공개 URL을 전달합니다
- `image_url`은 문자열로 바로 작성할 수도 있으며, `{ "url": "..." }`와 동일합니다
- `detail`은 이미지 분석 정밀도를 제어합니다: `auto`(기본값) / `low` / `high` /
`original`
- 이미지는 정상적으로 다운로드할 수 있어야 하며, 그렇지 않으면 `400`이 반환됩니다
**참고** 이 API의 블록 유형은 Responses API와 다릅니다(Responses는 `input_text` /
`input_image` 사용). 두 가지를 섞어 쓸 수 없으며, 잘못 지정하면 `400`이 반환됩니다.
items:
$ref: '#/components/schemas/Message'
example:
- role: system
content: You are a concise assistant.
- role: user
content: Explain quantum entanglement in one sentence.
stream:
type: boolean
description: >-
스트리밍 방식으로 반환할지 여부입니다(SSE 이벤트 스트림, `data: [DONE]`으로 종료). 기본값은
`false`입니다.
default: false
example: false
max_completion_tokens:
type: integer
description: >-
생성할 최대 token 수(추론 token 포함)입니다.
**참고** 본 시리즈 모델은 `max_completion_tokens`를 사용합니다. 기존 코드와의 호환을 위해
`max_tokens`만 전달하면 자동으로 `max_completion_tokens`로 간주됩니다. 다만 **이 두 필드를
동시에 전달하지 마세요** — `gpt-5.1` / `gpt-5.2` / `gpt-5.4`에서는 동시에 전달하면
`400`이 반환됩니다.
example: 2048
reasoning_effort:
type: string
description: >-
추론 깊이 제어입니다. 지정 가능한 값은 모델에 따라 다릅니다:
| 모델 | 지정 가능한 값 |
|---|---|
| `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna` / `gpt-5.5` |
`none`, `low`, `medium`, `high`, `xhigh` |
| `gpt-5.4` / `gpt-5.2` / `gpt-5.1` | `low`, `medium`, `high`,
`xhigh` |
추론 token은 출력 token으로 청구되며
`usage.completion_tokens_details.reasoning_tokens`에 집계됩니다.
enum:
- none
- low
- medium
- high
- xhigh
example: medium
verbosity:
type: string
description: >-
답변의 상세 정도: `low` / `medium` / `high`.
**참고** `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna` / `gpt-5.5`만
지원하며, 나머지 모델은 이 매개변수를 지원하지 않습니다.
enum:
- low
- medium
- high
example: low
temperature:
type: number
description: >-
샘플링 온도이며 값의 범위는 0 ~ 2입니다. 값이 낮을수록 출력이 결정적이 됩니다.
**참고** `gpt-5.5` / `gpt-5.4` / `gpt-5.2` / `gpt-5.1`만 지원합니다.
`gpt-5.6` 제품군은 기본값 `1`만 허용하며, 다른 값을 전달하면 `400`이 반환됩니다.
minimum: 0
maximum: 2
example: 0.7
top_p:
type: number
description: >-
뉴클리어스 샘플링 매개변수이며 값의 범위는 0 ~ 1입니다. `temperature`와 함께 조정하지 않는 것을
권장합니다.
**참고** `gpt-5.5` / `gpt-5.4` / `gpt-5.2` / `gpt-5.1`만 지원하며,
`gpt-5.6` 제품군은 이 매개변수를 지원하지 않습니다.
minimum: 0
maximum: 1
example: 0.9
frequency_penalty:
type: number
description: >-
빈도 페널티이며 값의 범위는 -2 ~ 2입니다. 양수 값은 token의 출현 빈도에 따라 페널티를 적용해 반복되는 내용을
줄입니다.
**참고** `gpt-5.4` / `gpt-5.2` / `gpt-5.1`만 지원하며, `gpt-5.6` 제품군과
`gpt-5.5`는 이 매개변수를 지원하지 않습니다.
minimum: -2
maximum: 2
example: 0.5
presence_penalty:
type: number
description: >-
존재 페널티이며 값의 범위는 -2 ~ 2입니다. 양수 값은 모델이 새로운 주제를 다루도록 유도합니다.
**참고** `gpt-5.4` / `gpt-5.2` / `gpt-5.1`만 지원하며, `gpt-5.6` 제품군과
`gpt-5.5`는 이 매개변수를 지원하지 않습니다.
minimum: -2
maximum: 2
example: 0.5
logprobs:
type: boolean
description: >-
각 출력 token의 로그 확률을 반환할지 여부입니다.
**참고** `gpt-5.4` / `gpt-5.2` / `gpt-5.1`만 지원하며, `gpt-5.6` 제품군과
`gpt-5.5`는 이 매개변수를 지원하지 않습니다.
default: false
example: true
top_logprobs:
type: integer
description: >-
각 위치에서 반환되는 후보 token 수이며 값의 범위는 0 ~ 5입니다. `logprobs: true`와 함께 사용해야
합니다.
**참고** 지원 범위는 `logprobs`와 동일합니다.
minimum: 0
maximum: 5
example: 2
'n':
type: integer
description: >-
생성할 후보 응답 수로, `choices` 배열에 여러 결과로 반환됩니다. 모든 token(각 후보의 출력 포함)이
청구됩니다.
default: 1
example: 1
seed:
type: integer
description: >-
랜덤 시드입니다. 동일한 시드와 매개변수 조합에서 모델은 가능한 한 일관된 결과를 반환합니다(최선의 노력이며 완전한
재현성은 보장되지 않습니다).
example: 42
response_format:
type: object
description: >-
출력 형식 제어:
- `{"type": "text"}`: 기본값인 자유 텍스트
- `{"type": "json_object"}`: 유효한 JSON을 반환하며, **`messages`에 `json`이라는
단어가 포함되어 있어야 합니다**. 그렇지 않으면 `400`이 반환됩니다
- `{"type": "json_schema", "json_schema": {...}}`: 지정한 JSON Schema에
따라 구조화된 결과를 출력하며, `"strict": true`와 함께 사용하면 스키마 준수를 강제할 수 있습니다
properties:
type:
type: string
enum:
- text
- json_object
- json_schema
example: json_schema
json_schema:
type: object
description: >-
`type`이 `json_schema`일 때 필수이며, `name`, `schema`, `strict` 필드를
포함합니다
tools:
type: array
description: >-
Function Calling(클라이언트 측 함수 호출, 호출당 요금 없음)에 사용하는 도구 목록입니다.
서버 측 도구(웹 검색, 코드 실행 등)는 이 API에서 제공하지 않으므로 [Responses
API](../responses/responses-reference)를 이용하세요.
items:
$ref: '#/components/schemas/FunctionTool'
tool_choice:
description: >-
도구 선택 제어: `"auto"`(기본값) / `"none"` / `"required"`, 또는 객체로 특정 함수를
지정합니다. 예: `{"type": "function", "function": {"name":
"get_weather"}}`.
oneOf:
- type: string
enum:
- none
- auto
- required
- type: object
parallel_tool_calls:
type: boolean
description: >-
모델이 한 턴 안에서 여러 도구를 병렬로 호출할 수 있는지 여부입니다. 기본값은 `true`이며, `false`로 설정하면
하나씩 순서대로 호출하도록 강제합니다.
default: true
example: true
prompt_cache_key:
type: string
description: 캐시 그룹화 키입니다. 접두사가 같은 요청에 동일한 값을 전달하면 Prompt 캐시 적중률이 높아집니다.
example: app-chat-v1
user:
type: string
description: 최종 사용자 식별자로, 호출 출처를 구분하는 데 사용합니다.
example: user-1024
ChatCompletionResponse:
type: object
properties:
id:
type: string
description: 이번 대화의 고유 식별자
example: chatcmpl-CvJ2p8mQxK7nR4wS
object:
type: string
enum:
- chat.completion
description: 응답 유형
example: chat.completion
created:
type: integer
description: 생성 타임스탬프
example: 1786705221
model:
type: string
description: 실제 사용된 모델 이름
example: gpt-5.6-sol
choices:
type: array
description: 생성 결과 목록(길이는 요청의 `n`과 동일)
items:
$ref: '#/components/schemas/Choice'
usage:
$ref: '#/components/schemas/Usage'
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: integer
description: HTTP 상태 오류 코드
message:
type: string
description: 오류 설명
type:
type: string
description: 오류 유형
param:
type: string
description: 관련 매개변수 이름
fallback_suggestion:
type: string
description: 오류 발생 시 제안
Message:
type: object
required:
- role
- content
properties:
role:
type: string
description: 메시지 역할
enum:
- system
- developer
- user
- assistant
- tool
example: user
content:
description: '메시지 내용: 문자열 또는 콘텐츠 블록 배열(`text` / `image_url` 혼합).'
oneOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/ContentBlock'
example: Explain quantum entanglement in one sentence.
FunctionTool:
type: object
required:
- type
- function
properties:
type:
type: string
enum:
- function
example: function
function:
type: object
description: 함수 정의
properties:
name:
type: string
example: get_weather
description:
type: string
example: 지정한 도시의 날씨 조회
parameters:
type: object
description: JSON Schema 형식의 매개변수 정의
Choice:
type: object
properties:
index:
type: integer
description: 결과 인덱스
example: 0
message:
$ref: '#/components/schemas/AssistantMessage'
logprobs:
type: object
description: 로그 확률 정보로, 요청에서 `logprobs`를 활성화한 경우에만 반환됩니다
finish_reason:
type: string
description: >-
종료 이유: `stop`은 정상 종료, `length`는 최대 token 제한 도달, `tool_calls`는 도구 호출이
필요한 경우
enum:
- stop
- length
- tool_calls
example: stop
Usage:
type: object
description: >-
Token 사용량 통계입니다. Prompt 캐시는 자동으로 적용되며, 캐시에 적중한 입력 token은 더 저렴한 캐시 요금으로
청구됩니다.
properties:
prompt_tokens:
type: integer
description: 입력 토큰 수
example: 18
completion_tokens:
type: integer
description: 출력 토큰 수 (추론 토큰 포함)
example: 42
total_tokens:
type: integer
description: 총 토큰 수
example: 60
prompt_tokens_details:
type: object
description: 상세 입력 토큰 정보
properties:
cached_tokens:
type: integer
description: 캐시에 적중한 token 수
example: 0
completion_tokens_details:
type: object
description: 상세 출력 토큰 정보
properties:
reasoning_tokens:
type: integer
description: 추론 토큰 수
example: 16
ContentBlock:
type: object
required:
- type
properties:
type:
type: string
description: |-
콘텐츠 유형
- `text`: 텍스트 블록
- `image_url`: 이미지 입력
enum:
- text
- image_url
example: image_url
text:
type: string
description: '`type=text`일 때의 텍스트 내용'
example: What is in this image?
image_url:
type: object
description: >-
이미지 입력(`type=image_url`인 경우). 이미지 URL 문자열로 바로 작성할 수도 있으며, `{ "url":
"..." }`와 동일합니다.
required:
- url
properties:
url:
type: string
description: 이미지의 공개 URL입니다. 정상적으로 다운로드할 수 있어야 하며, 그렇지 않으면 `400`이 반환됩니다
example: https://example.com/photo.png
detail:
type: string
description: |-
이미지 분석 정밀도
- `low`: 낮은 정밀도, token 소비가 적음
- `high`: 높은 정밀도, 더 세밀하게 인식
- `original`: 원본 이미지 크기로 분석
- `auto`(기본값): 모델이 자동으로 결정
enum:
- auto
- low
- high
- original
default: auto
example: auto
description: 멀티모달 콘텐츠 블록입니다. `type`으로 유형을 선언하고 해당 유형에 일치하는 필드만 채웁니다.
AssistantMessage:
type: object
properties:
role:
type: string
enum:
- assistant
example: assistant
content:
type: string
description: 모델이 생성한 텍스트 내용이며, 도구 호출이 트리거되면 `null`일 수 있습니다
example: >-
Quantum entanglement means the states of two particles are
correlated, so measuring one instantly determines the state of the
other.
tool_calls:
type: array
description: 모델이 호출을 요청한 도구 목록
items:
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: |-
##모든 API는 Bearer Token 인증이 필요합니다##
**API Key 받기:**
[API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 받으세요
**요청 헤더에 추가:**
```
Authorization: Bearer YOUR_API_KEY
```
````