채팅 완성 생성 (Create Chat Completion)

요청 본문 (Request Body)

지원되는 선택적 매개변수, 허용되는 값 및 기본값은 선택한 모델에 따라 다릅니다. 샘플링, 추론 또는 도구 옵션을 설정하기 전에 해당 모델 세부 정보를 확인하십시오.

modelstring필수

사용할 모델의 ID입니다. 사용 가능한 옵션은 모델(Models)을 참조하십시오.

messagesarray필수

대화를 구성하는 메시지 목록입니다.

각 메시지 객체에는 다음이 포함됩니다:

role (string): system, developer, user, assistant, tool, function
content (string | array | null): 메시지 내용

tool_calls를 포함하는 assistant 메시지의 경우, content는 생략하거나 null로 설정할 수 있습니다.

content가 배열인 경우, TokenLab은 호환되는 모델에 대해 구조화된 멀티모달 블록을 지원합니다:

텍스트: { "type": "text", "text": "..." }
이미지: { "type": "image_url", "image_url": { "url": "https://..." } }
비디오: { "type": "video_url", "video_url": { "url": "https://..." } }
오디오: { "type": "audio_url", "audio_url": { "url": "https://..." } }

멀티모달 입력의 경우, 공개적으로 접근 가능한 https URL을 사용하십시오. 지원되는 미디어 유형은 선택한 모델에 따라 다릅니다.

temperaturenumber

샘플링 온도입니다. 지원 여부, 허용되는 값 및 기본값은 선택한 모델에 따라 다릅니다. 기본값을 사용하려면 이 필드를 생략하십시오.

max_tokensinteger

생성할 최대 토큰 수입니다.

streamboolean기본값: false

true인 경우, 부분 메시지 델타가 SSE 이벤트로 전송됩니다.

stream_optionsobject

스트리밍을 위한 옵션입니다. 스트림 청크 내에서 토큰 사용량을 수신하려면 include_usage: true로 설정하십시오.

top_pnumber

뉴클리어스 샘플링(Nucleus sampling) 매개변수입니다. 이 값과 temperature 중 하나만 변경하는 것을 권장합니다.

frequency_penaltynumber

-2.0에서 2.0 사이의 숫자입니다. 양수 값은 반복되는 토큰에 페널티를 부여합니다.

presence_penaltynumber

-2.0에서 2.0 사이의 숫자입니다. 양수 값은 이미 텍스트에 존재하는 토큰에 페널티를 부여합니다.

stopstring | array

중단 시퀀스 또는 시퀀스 목록입니다. 지원 여부 및 시퀀스 제한은 선택한 모델에 따라 다릅니다.

toolsarray

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

tool_choicestring | object

모델이 도구를 사용하는 방식을 제어합니다. 옵션: auto, none, required 또는 특정 도구 객체.

parallel_tool_callsboolean

선택한 모델이 지원하는 경우, 한 번의 어시스턴트 턴에서 여러 도구 호출을 허용합니다.

max_completion_tokensinteger

완성을 위한 최대 토큰 수입니다. max_tokens의 대안이며, 최신 추론 기능이 활성화된 모델 제품군에 유용합니다.

reasoning_effortstring

이를 지원하는 모델에 대한 추론 노력(reasoning effort) 수준입니다. 허용되는 값은 선택한 모델에 따라 다릅니다.

Claude 모델의 경우, 이 값은 모델의 사고 방식을 설정합니다. 적응형 사고(adaptive thinking) 모델에서는 노력 수준을, 사고 예산을 사용하는 모델에서는 사고 예산을 설정합니다. none은 이를 허용하는 모델에서 사고 기능을 끕니다. 사고 기능이 켜져 있는 동안 Claude는 1이 아닌 temperature, top_k, 0.95~1 범위를 벗어난 top_p, 그리고 미리 채워진 어시스턴트 메시지를 거부합니다. 강제 tool_choice는 적응형 사고와는 작동하지만 사고 예산과는 작동하지 않습니다.

anthropic_optionsobject

Claude 모델을 위한 옵션입니다.

prompt_caching (boolean): 프롬프트 시작 부분을 캐싱하려면 true로 설정하십시오. TokenLab은 시스템 프롬프트의 끝과 최신 사용자 메시지를 캐시 포인트로 표시합니다. 동일한 내용으로 시작하는 이후 요청은 캐시에서 이를 읽어옵니다. 메시지에 이미 cache_control이 있는 경우, TokenLab은 캐시 포인트를 추가하지 않습니다.
prompt_caching_ttl (string): 5m(기본값) 또는 1h. 서비스 경로가 1시간을 지원하지 않는 경우, TokenLab은 5분을 사용하며 요청을 거부하지 않습니다.

extra.prompt_caching 및 extra.prompt_caching_ttl도 동일한 옵션으로 허용됩니다. 가격 및 캐시된 토큰 확인 방법은 프롬프트 캐싱(Prompt caching)을 참조하십시오.

seedinteger

이를 지원하는 모델에 대한 샘플링 시드(seed)입니다. 동일한 출력이 보장되지는 않습니다.

ninteger

생성할 완성본의 개수입니다(1-128).

logprobsboolean

로그 확률(log probabilities)을 반환할지 여부입니다.

top_logprobsinteger

반환할 상위 로그 확률의 개수입니다(0-20). logprobs: true가 필요합니다.

top_kinteger

이를 지원하는 모델에 대한 Top-K 샘플링입니다.

response_formatobject

응답 형식입니다. JSON 모드의 경우 {"type": "json_object"}를 사용하고, JSON 스키마의 경우 {"type": "json_schema", "json_schema": {...}}를 사용하십시오. 지원 여부는 선택한 모델에 따라 다릅니다.

logit_biasobject

지정된 토큰이 나타날 가능성을 수정합니다. 토큰 ID(문자열)를 -100에서 100 사이의 편향 값에 매핑하십시오.

userstring

남용 모니터링을 위해 최종 사용자를 나타내는 고유 식별자입니다.

응답 (Response)

idstring

완성본에 대한 고유 식별자입니다.

objectstring

항상 chat.completion입니다.

createdinteger

완성본이 생성된 Unix 타임스탬프입니다.

modelstring

완성에 사용된 모델입니다.

choicesarray

완성 선택지 목록입니다.

각 선택지에는 다음이 포함됩니다:

index (integer): 선택지의 인덱스
message (object): 생성된 메시지
finish_reason (string): 모델이 중단된 이유(예: stop, length, tool_calls)

모델이 사고하는 경우, message에는 다음이 포함될 수도 있습니다:

reasoning_content (string): 사고 텍스트. 일부 모델은 요약만 반환하거나 텍스트를 반환하지 않을 수 있습니다.
reasoning_details (array): 서명이 포함된 사고 블록. 예를 들어 도구 호출 후 사고와 함께 대화를 계속하려면, 어시스턴트 메시지에 이를 변경 없이 다시 보내십시오.

스트림에서는 동일한 필드가 delta.reasoning_content 및 delta.reasoning_details로 도착합니다.

usageobject

토큰 사용 통계입니다.

prompt_tokens (integer): 프롬프트의 토큰 수
completion_tokens (integer): 사고 토큰을 포함한 완성본의 토큰 수
total_tokens (integer): 사용된 총 토큰 수
completion_tokens_details.reasoning_tokens (integer): 모델이 보고하는 경우의 사고 토큰 수

요청

curl -X POST "https://api.tokenlab.sh/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 1000
  }'

멀티모달 예시 (Multimodal Example)

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this video briefly." },
        { "type": "video_url", "video_url": { "url": "https://example.com/demo.mp4" } }
      ]
    }
  ],
  "max_tokens": 64
}

응답

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1706000000,
  "model": "gpt-5.6-terra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

인증

BearerAuth

AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

"auto"
"verified"
"official"

요청 본문

application/json

model*string

사용할 모델의 ID (예: gpt-5.4, claude-sonnet-4-6)

messages*array<>

대화를 구성하는 메시지 목록

항목1 <= items

temperature?number

샘플링 온도 (0-2)

범위0 <= value <= 2

기본값1

top_p?number

뉴클리어스 샘플링 확률

범위0 <= value <= 1

기본값1

n?integer

생성할 완성본(completion)의 수

범위1 <= value <= 128

기본값1

stream?boolean

true인 경우 이벤트 스트림을 반환합니다.

기본값false

stop?|array<string>

중단 시퀀스

max_tokens?integer

생성할 최대 토큰 수

범위1 <= value

max_completion_tokens?integer

최신 추론 지원 모델 제품군을 위한 최대 완성 토큰 수

범위1 <= value

presence_penalty?number

존재 페널티 (-2 ~ 2)

범위-2 <= value <= 2

기본값0

frequency_penalty?number

빈도 페널티 (-2 ~ 2)

범위-2 <= value <= 2

기본값0

tools?array<>

모델이 호출할 수 있는 도구 목록

functions?array<>

공식 Chat Completions 계약에 의해 유지되는 지원 중단된 함수 정의입니다.

function_call?|

공식 Chat Completions 계약에 의해 유지되는 지원 중단된 함수 호출 선택입니다.

tool_choice?|

호출할 함수를 제어합니다.

response_format?

응답 형식 사양

seed?integer

결정론적 생성을 위한 시드(Seed)

user?string

남용 탐지를 위한 최종 사용자 식별자

stream_options?

사용량 청크 포함과 같은 스트리밍 옵션입니다.

parallel_tool_calls?boolean

모델이 병렬 도구 호출을 수행할 수 있는지 여부.

reasoning_effort?string

호환되는 모델 제품군을 위한 추론 노력 힌트입니다.

logprobs?boolean

출력 토큰에 대한 로그 확률을 반환할지 여부입니다.

top_logprobs?integer

logprobs가 활성화된 경우 각 위치에서 반환할 가장 가능성이 높은 토큰의 수입니다.

범위0 <= value <= 20

logit_bias?

토큰별 로짓 편향(logit bias) 맵입니다.

modalities?array<string>

텍스트나 오디오와 같이 요청된 출력 양식(modality)입니다.

audio?

오디오 양식을 요청할 때의 오디오 출력 구성입니다.

translation_options?

Chat Completions를 통해 오디오나 비디오를 번역하는 모델을 위한 언어 설정입니다.

prediction?

드래프트 또는 추측 디코딩(speculative decoding)을 지원하는 모델에 대한 예측 힌트입니다.

service_tier?|

TokenLab은 이 요청을 표준 서비스 티어로 처리합니다. auto 및 default는 전달됩니다. flex, priority, fast, ultrafast와 같은 기타 값은 무시되며 표준 가격으로 과금됩니다.

anthropic_options?

Claude 모델을 위한 옵션입니다.

extra?

확장 옵션입니다. extra.prompt_caching 및 extra.prompt_caching_ttl은 anthropic_options 필드와 동일합니다.

[key: string]?any

채팅 완성 생성 (Create Chat Completion)

요청 본문 (Request Body)

응답 (Response)

멀티모달 예시 (Multimodal Example)

인증

헤더

요청 본문

응답

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

채팅 완성 생성 (Create Chat Completion)

요청 본문 (Request Body)Copy Anchor Link

응답 (Response)Copy Anchor Link

멀티모달 예시 (Multimodal Example)Copy Anchor Link

인증Copy Anchor Link

헤더Copy Anchor Link

요청 본문Copy Anchor Link

응답Copy Anchor Link

200application/json

400application/json

401application/json

402application/json

429application/json

500application/json

502application/json

503application/json

요청 본문 (Request Body)

응답 (Response)

멀티모달 예시 (Multimodal Example)

인증

헤더

요청 본문

응답

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`