Chat Completions

OpenAI 호환 Chat Completions API로 텍스트, 멀티모달 및 도구 호출 응답을 생성합니다.

Chat Completions API는 메시지 목록을 바탕으로 모델 응답을 생성합니다. 일반 텍스트 대화, 멀티모달 입력, 스트리밍 출력, 구조화된 출력 및 함수 도구 호출에 적합합니다. 모델별로 사용 가능한 입력 타입과 고급 매개변수가 다를 수 있으므로 현재 API 키에서 사용 가능한 모델과 실제 호출 결과를 기준으로 확인하세요.

POST/v1/chat/completions

지정된 메시지 목록을 바탕으로 모델 응답을 생성합니다. 일반 응답과 SSE 스트리밍 응답을 지원합니다. 이미지, 오디오, 도구 호출, 구조화된 출력 등의 고급 기능은 선택한 모델에 따라 다릅니다.

모델을 변경할 때는 최소 텍스트 요청으로 기본 기능을 먼저 검증한 후 고급 매개변수를 하나씩 활성화하는 것이 좋습니다.

인증

bearerAuth

인증Bearer <token>

Authorization Header에 Bearer your-api-key를 사용합니다.

전달 위치: header

요청 본문

모델의 입력 모달리티에 맞는 요청 구조를 선택하세요. 세 보기 모두 동일한 Chat Completions 엔드포인트와 공통 생성 매개변수를 사용합니다.

application/json

텍스트 대화

일반 대화, 콘텐츠 생성, 텍스트 추론에 적합합니다. 메시지 내용을 문자열로 전달할 수 있습니다.

model: 현재 계정에서 사용할 수 있는 텍스트 모델 ID입니다.
messages[].role: 메시지 역할입니다. 예: user, system, assistant.
messages[].content: 문자열 형식의 텍스트 메시지입니다.

application/json

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "안녕하세요! 한 문장으로 자신을 소개해 주세요."
    }
  ]
}

텍스트 대화 요청입니다. 사용자 메시지는 문자열 또는 text 블록만 포함하는 콘텐츠 배열로 전달할 수 있습니다.

model*string

사용할 텍스트 모델 ID입니다. 모델 목록에서 현재 계정에 표시되며 텍스트 입력을 지원하는 모델 ID를 복사하세요.

길이1 <= length

messages*array<|||||>

전송 순서대로 정렬한 텍스트 대화 메시지 목록입니다.

항목1 <= items

store?boolean|null

이번 채팅 완성 출력을 저장할지 지정합니다. 적용 여부는 선택한 모델과 채널에 따라 다릅니다.

기본값false

reasoning_effort?string|null

추론 모델의 추론 강도입니다. 허용 값은 선택한 모델에 따라 다릅니다. none은 추론을 명시적으로 비활성화합니다.

기본값"medium"

허용 값

"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
"max"
null

metadata?|null

요청에 추가하는 키-값 정보입니다. 키는 최대 64자, 값은 최대 512자입니다.

필드properties <= 16

modalities?array<>|null

모델이 생성할 출력 타입입니다. 기본적으로 텍스트만 생성합니다.

prediction?|null

예상 출력의 대부분을 알고 있을 때 사용하는 예측 콘텐츠 설정입니다.

audio?|null

오디오 출력 요청에 사용하는 형식 및 음성 설정입니다.

temperature?number|null

샘플링 온도입니다. 일반적으로 temperature 또는 top_p 중 하나만 조정합니다. 지원 여부는 선택한 모델에 따라 다릅니다.

범위0 <= value <= 2

기본값1

top_p?number|null

Nucleus 샘플링의 누적 확률입니다. 일반적으로 temperature 또는 top_p 중 하나만 조정합니다. 지원 여부는 선택한 모델에 따라 다릅니다.

범위0 <= value <= 1

기본값1

n?integer|null

입력마다 생성할 후보 응답 수입니다. 여러 후보를 생성하면 사용량이 증가합니다.

범위1 <= value <= 128

기본값1

stop?string|array<string>|null

최대 네 개의 중지 시퀀스입니다. 지원 여부와 구체적인 동작은 선택한 모델에 따라 다릅니다.

max_tokens?integer|null

사용 중단 예정

이전 버전의 최대 출력 토큰 매개변수입니다. max_completion_tokens를 사용하는 것이 좋습니다.

범위1 <= value

max_completion_tokens?integer|null

완성에서 생성할 수 있는 최대 토큰 수입니다. 사용자에게 표시되는 출력과 추론 토큰을 포함합니다.

presence_penalty?number|null

토큰이 이미 등장했는지에 따라 페널티를 적용하여 새로운 주제를 다룰 가능성을 높입니다. 지원 여부는 선택한 모델에 따라 다릅니다.

범위-2 <= value <= 2

기본값0

frequency_penalty?number|null

토큰의 등장 빈도에 따라 페널티를 적용하여 반복 콘텐츠의 가능성을 낮춥니다. 지원 여부는 선택한 모델에 따라 다릅니다.

범위-2 <= value <= 2

기본값0

logit_bias?|null

토큰 ID를 -100부터 100까지의 편향 값에 매핑합니다.

logprobs?boolean|null

출력 토큰의 로그 확률을 반환할지 지정합니다. 지원 여부는 선택한 모델에 따라 다릅니다.

기본값false

user?string

사용 중단 예정

더 이상 권장되지 않는 최종 사용자 식별자입니다. 안전 모니터링에는 safety_identifier, 캐시 라우팅에는 prompt_cache_key를 사용하세요.

safety_identifier?string|null

안전 및 오용 모니터링을 위한 안정적인 최종 사용자 식별자입니다. 개인정보를 포함하지 않는 해시 값을 전달하는 것이 좋습니다.

길이length <= 64

prompt_cache_key?string|null

유사한 요청의 캐시 적중률을 높이기 위한 안정적인 키입니다. 개인정보나 다른 민감 정보를 포함하지 마세요.

prompt_cache_options?|null

요청 수준의 프롬프트 캐시 설정입니다.

prompt_cache_retention?string|null

사용 중단 예정

더 이상 권장되지 않는 캐시 보관 설정입니다. prompt_cache_options.ttl을 사용하세요.

허용 값

"in_memory"
"24h"
null

verbosity?string|null

텍스트 응답의 상세 수준을 제어합니다. 지원 여부는 선택한 모델에 따라 다릅니다.

기본값"medium"

허용 값

"low"
"medium"
"high"
null

moderation?|null

입력과 출력의 콘텐츠 검토 정책을 설정합니다.

service_tier?string|null

요청에 사용할 서비스 등급입니다. 사용 가능 여부는 계정과 상위 서비스의 기능에 따라 다릅니다.

기본값"auto"

허용 값

"auto"
"default"
"flex"
"scale"
"priority"
"fast"
null

stream_options?|null

stream: true일 때만 사용하는 스트리밍 응답 옵션입니다.

response_format?||

모델의 출력 형식을 지정합니다. 구조화된 출력 기능은 선택한 모델에 따라 다릅니다.

seed?integer|null

사용 중단 예정

결정적 샘플링을 최대한 시도하는 Beta 매개변수이며 완전한 결정성을 보장하지 않습니다.

tools?array<|>

모델이 호출할 수 있는 도구 목록입니다.

항목items <= 128

functions?array<>

사용 중단 예정

이전 버전의 함수 정의입니다. tools로 변경하는 것이 좋습니다.

tool_choice?|||

모델의 도구 호출 여부, 지정 도구의 강제 호출 또는 허용 도구 집합을 제어합니다.

function_call?|

사용 중단 예정

이전 버전의 함수 선택 매개변수입니다. tool_choice로 변경하는 것이 좋습니다.

parallel_tool_calls?boolean

모델이 한 응답에서 여러 도구를 병렬로 호출하도록 허용할지 지정합니다.

기본값true

stream?boolean|null

true이면 Server-Sent Events를 통해 채팅 완성 데이터 청크를 증분 방식으로 반환합니다.

기본값false

top_logprobs?integer|null

각 토큰 위치에서 반환할 가능성이 높은 토큰 수입니다. 사용할 때 logprobs: true도 설정해야 합니다. 지원 여부는 선택한 모델에 따라 다릅니다.

범위0 <= value <= 20

web_search_options?

이미지와 오디오 입력은 해당 모달리티를 지원하는 모델에서만 사용할 수 있습니다. 현재 계정에서 사용 가능한 모델과 실제 API 기능을 기준으로 확인하세요.

응답 본문

`application/json`

curl -X POST "https://example.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "안녕하세요! 한 문장으로 자신을 소개해 주세요."
      }
    ]
  }'

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 무엇을 도와드릴까요?",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

OpenAI Chat Completions 공식 문서상위 서비스의 프로토콜 정의와 최신 필드 변경 사항을 확인합니다.

인증

요청 본문

응답 본문

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

502application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`