텍스트
채팅 완성 생성 (Create Chat Completion)
채팅 메시지에 대한 완성을 생성합니다
요청 본문 (Request Body)
지원되는 선택적 매개변수, 허용되는 값 및 기본값은 선택한 모델에 따라 다릅니다. 샘플링, 추론(reasoning) 또는 도구 옵션을 설정하기 전에 모델 세부 정보를 확인하십시오. 일부 모델에서 n을 1보다 크게 설정하는 것과 같이 모델이 처리할 수 없는 제어 설정은 4xx 오류와 함께 거부됩니다. seed 또는 페널티와 같은 사소한 샘플링 제어는 무시될 수 있습니다.
사용할 모델의 ID입니다. 사용 가능한 옵션은 모델을 참조하십시오.
대화를 구성하는 메시지 목록입니다.
각 메시지 객체에는 다음이 포함됩니다:
role(string):system,developer,user,assistant,tool,functioncontent(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": "input_audio", "input_audio": { "data": "https://... 또는 base64 데이터 URL", "format": "wav" } }, 또는{ "type": "audio_url", "audio_url": { "url": "https://..." } }
멀티모달 입력의 경우 공개적으로 접근 가능한 https URL을 사용하십시오. 이미지는 base64 데이터 URL로 전송할 수도 있습니다. 지원되는 미디어 유형은 선택한 모델에 따라 다릅니다.
샘플링 온도입니다. 지원 여부, 허용되는 값 및 기본값은 선택한 모델에 따라 다릅니다. 기본값을 사용하려면 이 필드를 생략하십시오.
생성할 최대 토큰 수입니다. max_tokens 또는 max_completion_tokens 중 하나만 전송하십시오. 둘 다 전송하면 다른 프로토콜을 통해 제공되는 모델이 요청을 거부할 수 있습니다.
생각(thinking)을 하는 모델의 경우, 생각 토큰도 이 제한에 포함됩니다. 제한이 너무 작으면 전체 예산이 생각하는 데 소모되어 빈 메시지 본문만 남을 수 있으며, 사용된 토큰은 여전히 과금됩니다. 제한을 높이거나, 모델이 허용하는 경우(예: "reasoning_effort": "none") 생각 기능을 끄십시오. deepseek-v4.1-flash (별칭 deepseek-flash) 모델에서는 "thinking": {"type": "disabled"}를 사용하여 끌 수도 있습니다.
요청이 실행되기 전에 TokenLab은 잔액이 이 최대치를 충족하는지 확인합니다. 잔액이 적을 때 매우 큰 값을 설정하면 답변이 짧더라도 402 오류가 반환될 수 있습니다.
falsetrue인 경우, 부분 메시지 델타가 서버 전송 이벤트(SSE)로 전송됩니다. 스트리밍을 참조하십시오.
긴 출력(수천 토큰 이상)의 경우, 전체 응답을 기다리는 동안 클라이언트와 프록시의 시간 초과를 방지하기 위해 stream: true로 설정하십시오.
스트리밍 옵션입니다. data: [DONE] 이전에 토큰 사용량을 포함하는 추가 청크를 받으려면 include_usage: true로 설정하십시오. 이 설정이 없으면 스트림에 사용량 정보가 포함되지 않습니다.
뉴클리어스 샘플링(Nucleus sampling) 매개변수입니다. 이 값이나 temperature 중 하나만 변경하는 것을 권장합니다.
-2.0에서 2.0 사이의 숫자입니다. 양수 값은 반복되는 토큰에 페널티를 부여합니다.
-2.0에서 2.0 사이의 숫자입니다. 양수 값은 텍스트에 이미 존재하는 토큰에 페널티를 부여합니다.
정지 시퀀스 또는 시퀀스 목록입니다. 지원 여부 및 시퀀스 제한은 선택한 모델에 따라 다릅니다.
모델이 호출할 수 있는 도구 목록입니다(함수 호출). 각 도구는 { "type": "function", "function": { "name": "...", "description": "...", "parameters": { ... } } } 형태입니다. 구조화된 출력 및 도구 호출을 참조하십시오.
모델이 도구를 사용하는 방식을 제어합니다. 옵션: auto, none, required, 또는 특정 도구를 강제하기 위한 { "type": "function", "function": { "name": "..." } }.
선택한 모델이 지원하는 경우, 한 번의 어시스턴트 턴에서 여러 도구 호출을 허용합니다.
생각 토큰을 포함한 완성에 대한 상한선입니다. 최신 OpenAI 모델 제품군에서 사용하는 max_tokens의 대안입니다. 둘 중 하나만 전송하십시오.
이를 지원하는 모델에 대한 추론 노력(reasoning effort) 수준입니다. 허용되는 값은 선택한 모델에 따라 다릅니다.
Claude 모델의 경우, 이 값은 모델의 생각을 설정합니다: 적응형 생각(adaptive thinking) 모델에서는 노력 수준을, 이를 사용하는 모델에서는 생각 예산을 설정합니다. none은 이를 허용하는 모델에서 생각 기능을 끕니다. 모델이 지원하지 않는 값을 설정하면 400 오류, invalid_value 코드와 함께 거부되며 오류 메시지에 지원되는 값이 나열됩니다. 생각이 켜져 있는 동안 Claude는 1이 아닌 temperature, top_k, 0.95–1 범위를 벗어난 top_p, 그리고 미리 채워진 어시스턴트 메시지를 거부합니다. 강제된 tool_choice는 적응형 생각과는 작동하지만 생각 예산과는 작동하지 않습니다.
Claude 모델을 위한 옵션입니다.
prompt_caching(boolean): 프롬프트 시작 부분을 캐시하려면true로 설정하십시오. TokenLab은 시스템 프롬프트의 끝과 최신 사용자 메시지를 캐시 지점으로 표시합니다. 동일한 내용으로 시작하는 이후 요청은 캐시에서 읽어옵니다. 이 옵션 또는 사용자 고유의cache_control마크 중 하나만 사용하십시오.prompt_caching_ttl(string):5m(기본값) 또는1h. 요청을 처리하는 서비스가 1시간 동안 캐시를 유지할 수 없는 경우, TokenLab은 요청을 거부하는 대신 5분 캐시를 사용할 수 있습니다.
extra.prompt_caching 및 extra.prompt_caching_ttl도 동일한 옵션으로 허용됩니다. 가격 및 캐시된 토큰 확인 방법은 프롬프트 캐싱을 참조하십시오.
이를 지원하는 모델에 대한 샘플링 시드입니다. 동일한 출력이 보장되지는 않습니다.
생성할 완성의 개수입니다. 이를 지원하는 모델은 1-128을 허용합니다. 많은 모델이 1만 지원합니다.
로그 확률(log probabilities)을 반환할지 여부입니다.
반환할 상위 로그 확률의 개수(0-20)입니다. logprobs: true가 필요합니다.
이를 지원하는 모델에 대한 Top-K 샘플링입니다.
응답 형식입니다. {"type": "text"} (기본값), JSON 모드의 경우 {"type": "json_object"}, 또는 JSON 스키마의 경우 {"type": "json_schema", "json_schema": {"name": "...", "schema": {...}, "strict": true}}를 사용하십시오. 지원 여부는 선택한 모델에 따라 다릅니다. 구조화된 출력 및 도구 호출을 참조하십시오.
지정된 토큰이 나타날 가능성을 수정합니다. 토큰 ID(문자열)를 -100에서 100 사이의 편향 값에 매핑합니다. 지원 여부는 선택한 모델에 따라 다릅니다.
TokenLab은 표준 서비스 계층에서 채팅 요청을 처리하고 과금합니다. auto 및 default가 허용됩니다. flex 또는 priority와 같은 다른 값은 요청에서 제거되며, 요청은 표준 가격으로 과금됩니다.
남용 모니터링을 위해 최종 사용자를 나타내는 고유 식별자입니다.
응답 (Response)
완성에 대한 고유 식별자입니다.
항상 chat.completion입니다.
완성이 생성된 Unix 타임스탬프입니다.
완성에 사용된 모델입니다.
완성 선택 항목 목록입니다.
각 선택 항목에는 다음이 포함됩니다:
index(integer): 선택 항목의 인덱스message(object): 생성된 메시지finish_reason(string): 모델이 중단된 이유 (예:stop,length,tool_calls,content_filter)
모델이 생각하는 경우, message에는 다음이 포함될 수도 있습니다:
reasoning_content(string): 생각 텍스트. 일부 모델은 요약만 반환하거나 텍스트를 반환하지 않습니다.reasoning_details(array): 서명이 포함된 생각 블록. 예를 들어 도구 호출 후 생각 기능을 사용하여 대화를 계속하려면, 어시스턴트 메시지에 이를 변경하지 않고 다시 보내십시오.
스트림에서 동일한 필드가 delta.reasoning_content 및 delta.reasoning_details로 도착합니다.
토큰 사용 통계입니다.
prompt_tokens(integer): 프롬프트의 토큰 수completion_tokens(integer): 생각 토큰을 포함한 완성의 토큰 수total_tokens(integer): 사용된 총 토큰 수prompt_tokens_details.cached_tokens(integer): 캐시에서 읽은 프롬프트 토큰 수cache_creation_input_tokens(integer): 캐시에 기록된 프롬프트 토큰 수. 값이 0보다 클 때만 표시됩니다.completion_tokens_details.reasoning_tokens(integer): 모델이 보고하는 경우의 생각 토큰 수
스트림에서 사용량은 stream_options.include_usage가 true일 때만 도착합니다.
요청
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
}응답
{
"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
}
}스트리밍 (Streaming)
stream: true를 설정하면 응답은 text/event-stream이 됩니다. 각 이벤트는 data: {...} 형태이며, choices[].delta에 새로운 텍스트, 도구 호출 인수 또는 생각 텍스트가 포함된 chat.completion.chunk 객체를 가집니다. 스트림은 data: [DONE]으로 끝납니다. :로 시작하는 줄은 유지 관리용 주석이므로 무시하십시오. [DONE] 없이 또는 finish_reason 없이 끝나는 스트림은 불완전한 것입니다. 스트리밍을 참조하십시오.
오류 (Errors)
오류는 OpenAI 스타일의 error 객체를 사용합니다. 일반적인 경우: 잘못된 필드나 모델이 허용하지 않는 값에 대해 400, 잘못된 키에 대해 401, 잔액 부족에 대해 402, 입력이 크기 제한을 초과한 경우 413, 속도 제한에 대해 429가 발생합니다. API 오류 처리를 참조하십시오.
인증
BearerAuth API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.
위치: header
헤더
요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.
허용 값
- "auto"
- "verified"
- "official"
동일한 요청이 두 번 실행되지 않도록 방지하는 선택적 키입니다. 각 요청마다 UUID와 같은 새로운 고유 값을 전송하고, 타임아웃 후 재시도 시에도 동일한 값을 유지하십시오. 동일한 키를 사용한 재시도는 다시 실행되지 않으며, idempotency_replay_unavailable와 함께 409를 반환하거나, 본문이 변경된 경우 일반적으로 idempotency_conflict를 반환합니다. 예외: 스트리밍되지 않는 결과가 클라이언트 연결 해제 후 완료된 경우, 24시간 이내에 동일한 키와 본문으로 재시도하면 Idempotent-Replayed: true 헤더와 함께 해당 결과(최대 1MB)를 반환하며 추가 비용은 청구되지 않습니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성 보호를 받지 못합니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.
1 <= length <= 255요청 본문
application/json
응답
application/json
application/json
application/json
application/json
application/json
application/json
application/json