본문으로 건너뛰기

Chat Completions

대화 입력으로 받는 OpenAI 호환 응답

messages 요청 필드와 응답 종료 이유, 스트리밍을 설명하고, 이미지 입력, 이미지 생성 결과와 도구 호출을 쓰는 조건을 안내합니다.

페이지 목차
POST
https://gw.letsur.ai/v1/chat/completions
인증Authorization: Bearer <API_KEY>

요청 필드

대화를 messages 배열에 담아 보내면 게이트웨이가 OpenAI 호환 형식으로 응답합니다. Chat Completions로 텍스트 생성, 이미지 입력, 도구 호출, 스트리밍과 이미지 생성 결과를 요청할 수 있습니다. 이 기능들을 모든 모델이 지원하지는 않으며, 사용할 모델의 지원 여부를 확인하는 방법은 모델별 지원 여부에 있습니다. Responses, Messages, Embeddings와의 차이는 API 형식 선택의 비교 표에 있습니다.

기본값 칸의 -는 기본값이 명시되지 않았다는 뜻입니다.

필드타입요구 여부기본값설명
modelstring필수-모델 코드 (에셋)
messagesarray필수-{role, content} 객체의 배열
temperaturenumber선택10 ~ 2
top_pnumber선택1누적 확률을 기준으로 다음 토큰 후보를 선택하는 설정
max_tokensinteger선택모델별응답 최대 토큰
streamboolean선택falseServer-Sent Events 스트리밍
stream_optionsobject선택-마지막 사용량 요약을 요청하는 옵션 (include_usage: true)
stopstring | array선택-응답 중단 시퀀스
ninteger선택1응답 개수 (대부분 1)
toolsarray선택-도구 호출 정의
tool_choicestring | object선택auto도구 선택 방식
response_formatobject선택-응답 형식 (JSON 모드 등)

모델별 지원 여부

위 표의 파라미터와 이미지 입력, 도구 호출, JSON 모드, 스트리밍은 이 엔드포인트로 요청할 수 있지만, 지원 여부와 세부 제한은 요청의 model이 가리키는 모델마다 다릅니다. 사용할 모델의 지원 여부는 에셋 화면의 표시값에서 확인합니다. 필요한 정보가 없다면 그 페이지에 안내된 문의 방법을 따르세요.

모델이 지원하지 않는 파라미터를 포함한 요청은 실패할 수 있습니다. 이미지 입력을 지원하지 않는 모델에 이미지를 보내거나 응답 형식을 지원하지 않는 모델에 response_format을 보냈을 때의 오류 코드는 오류와 복구에 있습니다.

messages 배열

role의미
system시스템 프롬프트 (모델 행동 지정)
user사용자 입력
assistant모델의 이전 응답 (대화 이어가기)
tool도구 호출 결과 (도구 호출 시)

content에는 텍스트 문자열이나 배열을 지정합니다. 이미지를 함께 보낼 때는 배열을 사용합니다. 배열의 항목 형식은 이미지 입력에서 확인합니다.

응답 (200)

{ "id": "chatcmpl-...", "object": "chat.completion", "created": 1730000000, "model": "<MODEL_CODE>", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 12, "completion_tokens": 48, "total_tokens": 60 }, "estimated_cost": { "amount": "0.00032400", "currency": "unit", "disclaimer": "Estimated based on published pricing. Actual charges may differ." } }

아래 표의 [0]은 첫 번째 선택지를 가리킵니다. 여러 선택지가 반환되면 choices[]의 각 항목을 확인하세요.

필드설명
id호출 응답의 식별자
model응답을 생성한 모델의 식별자
choices[0].message.content모델 응답 본문
choices[0].message.images[]이미지 생성 결과를 반환하는 모델이 생성한 이미지 배열 (이미지 생성 결과)
choices[0].finish_reasonstop / length / tool_calls / content_filter (finish_reason 별 의미)
estimated_cost비스트리밍 응답 최상위의 호출별 비용 객체. 영문 disclaimer는 응답 문자열 그대로 반환. 값의 의미와 null 처리 기준은 요청별 비용을 따름

종료 이유에 따른 다음 행동

finish_reason은 응답 종료 이유를 나타냅니다. 같은 200 OK라도 값에 따라 의미가 다릅니다.

값뜻과 다음 행동
stop모델이 응답 생성을 끝냈습니다. 응답 내용을 확인하고 애플리케이션에 필요한 형식과 조건을 만족하는지 검사합니다.
length응답이 max_tokens 또는 모델 컨텍스트 한도에 도달해 잘렸습니다. 출력 상한이 부족했다면 모델 한도 안에서 max_tokens를 늘리고, 전체 컨텍스트가 부족했다면 입력을 줄입니다. 나머지 응답이 필요하면 대화에 부분 응답을 포함해 다시 요청합니다.
tool_calls모델이 도구 호출을 요청했습니다. 응답 본문 대신 tool_calls 필드를 확인하고 도구 호출 절차에 따라 함수를 실행한 뒤 결과를 보냅니다.
content_filter공급사 안전 필터가 응답을 차단했습니다. 응답 본문은 비거나 짧을 수 있으니 클라이언트에서 따로 처리합니다. 응답에 담긴 설명과 모델의 입력 조건을 확인합니다. 같은 요청을 자동으로 반복하지 말고, 필요한 입력을 수정한 뒤 다시 요청할지 판단합니다.

요청과 응답 예시

아래 예제는 실행 환경의 LETSUR_API_KEY 환경 변수를 읽습니다. 키 설정과 첫 실행 방법은 첫 API 호출에 있습니다.

SDK 예제에서는 자동 재시도를 끕니다. timeout이나 응답 유실 뒤의 재전송 여부는 오류와 복구의 기준에 따라 판단합니다.

cURL
curl https://gw.letsur.ai/v1/chat/completions \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<MODEL_CODE>", "messages": [{"role": "user", "content": "안녕"}] }'

스트리밍

stream: true로 요청하면 게이트웨이가 응답을 Server-Sent Events(SSE)로 나누어 보냅니다.

cURL
curl https://gw.letsur.ai/v1/chat/completions \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<MODEL_CODE>", "messages": [{"role": "user", "content": "안녕"}], "stream": true, "stream_options": {"include_usage": true} }'

다음 설명용 예시는 delta.role이 든 첫 응답 조각을 빼고, 텍스트가 든 응답 조각부터 보여 줍니다.

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"안"},"finish_reason":null}]} data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"녕"},"finish_reason":null}]} ... data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":48,"total_tokens":60},"estimated_cost":{"amount":"0.00032400","currency":"unit","disclaimer":"Estimated based on published pricing. Actual charges may differ."}} data: [DONE]
시점응답 조각
첫 응답 조각delta.role: "assistant"
중간 응답 조각delta.content에 부분 텍스트
마지막 사용량 응답 조각stream_options.include_usage: true일 때 누적 usage와 계산 가능한 경우 estimated_cost
종료 신호data: [DONE]

누적 usage는 stream_options.include_usage: true를 지정했을 때 마지막 사용량 응답 조각에 들어 있습니다. 계산할 수 있는 호출 비용은 같은 응답 조각의 estimated_cost에 있습니다.

스트리밍 끊김 처리

스트리밍 응답은 마지막 응답 조각과 [DONE]을 받기 전에 끊길 수 있습니다. 클라이언트는 [DONE]을 받았는지 기록해 두고, 다음 상황을 구분해 처리합니다.

상황처리
마지막 사용량 응답 조각을 받지 못했거나 비용이 null임요청별 비용의 기준에 따라 비용을 0으로 저장하지 않습니다.
[DONE]을 받기 전에 연결이 끊김그때까지 받은 출력을 부분 응답으로 남깁니다. 연결이 끊겼다는 이유만으로 같은 요청을 바로 다시 보내지 않습니다.
오류 응답을 받음HTTP 상태와 type, error_ref를 기록하고 오류 코드의 기준으로 처리합니다.

이미지 입력

이미지 입력을 지원하는 모델에는 content 배열에 이미지를 넣어 보낼 수 있습니다.

client.chat.completions.create( model="<VISION_MODEL_CODE>", messages=[{ "role": "user", "content": [ {"type": "text", "text": "이 이미지를 설명해 줘"}, {"type": "image_url", "image_url": {"url": "https://.../image.png"}}, ], }], )
입력 형식값
URL{"type": "image_url", "image_url": {"url": "https://..."}}
Base64{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}

이미지 크기와 해상도 제한은 모델마다 다릅니다. 사용할 이미지의 조건은 에셋 화면의 표시값과 확인 방법에 있습니다.

이미지 생성 결과

Chat Completions 응답으로 이미지 생성 결과를 반환하는 이미지 모델에 일반 Chat Completions 요청처럼 messages에 프롬프트를 포함해 보내면 생성된 이미지가 choices[0].message.images[]로 반환됩니다. 이미지 모델마다 호출하는 엔드포인트가 다르니, 어떤 모델이 이 방식으로 결과를 반환하는지는 이미지와 영상 만들기의 모델별 호출 경로에서 확인합니다.

{ "choices": [ { "message": { "role": "assistant", "content": "...", "images": [ { "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." } } ] } } ] }

이 방식으로 결과를 반환하는 모델의 현재 모델 코드는 에셋에 있습니다.

도구 호출

함수 도구 호출에서는 모델이 함수 이름과 인수를 응답에 포함해 애플리케이션에 실행을 요청합니다. 애플리케이션은 요청의 tools에 사용할 수 있는 함수와 입력 형식을 정의해 보내고, 응답으로 받은 호출 요청을 처리합니다.

tools = [{ "type": "function", "function": { "name": "get_weather", "description": "도시의 현재 날씨를 가져옵니다.", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], }, }, }] response = client.chat.completions.create( model="<TOOL_CALLING_MODEL_CODE>", messages=[{"role": "user", "content": "서울 날씨 알려 줘"}], tools=tools, tool_choice="auto", )

도구 호출 정보는 응답의 choices[0].message.tool_calls에 들어 있습니다. 위 예제는 호출 요청을 받는 단계까지 보여 줍니다. 이 단계에서는 사용자에게 돌려줄 최종 답이 아직 완성되지 않았습니다. 함수는 애플리케이션이 실행합니다.

후속 요청의 messages는 아래 구조로 만듭니다. ID, 함수 인수와 결과는 실제 응답과 실행 결과로 바꿉니다.

[ {"role": "user", "content": "서울 날씨 알려 줘"}, { "role": "assistant", "tool_calls": [{ "id": "call_example", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"서울\"}"} }] }, {"role": "tool", "tool_call_id": "call_example", "content": "날씨 조회 함수의 실제 실행 결과"} ]
  1. 이전 대화 뒤에 반환받은 assistant 메시지를 넣습니다. tool_calls는 지우지 않고 그대로 둡니다.
  2. 이어서 각 도구의 실행 결과를 넣고, tool_call_id에는 그 결과를 만든 호출의 id를 지정합니다. 호출이 여러 개면 결과를 호출마다 대응시킵니다.
  3. 같은 모델과 도구 정의로 다시 요청합니다.
  4. 최종 응답의 내용과 finish_reason을 확인합니다.
tool_choice의미
"auto" (기본)모델이 도구 호출 여부를 판단합니다
"none"모델이 도구 호출을 요청하지 않습니다
"required"모델이 도구 호출을 요청하도록 지정합니다. 실제 실행은 애플리케이션이 합니다
{"type": "function", "function": {"name": "..."}}모델이 호출을 요청할 함수를 지정합니다

도구 호출 지원 여부와 요청 형식은 모델마다 다릅니다. 선택한 모델의 지원 범위를 확인하는 방법은 모델별 지원 여부에 있습니다.

오류와 복구

응답을 받지 못한 요청을 다시 보내면 추가 비용이 생길 수 있습니다

timeout이나 응답 유실 뒤 같은 요청을 다시 보내면 별도 호출로 처리됩니다. 다시 보내기 전에 동기 호출의 재시도와 비용 확인에 따라 원래 호출과 새 호출을 구분하세요.

이 엔드포인트에서 주로 확인할 오류와 대응은 다음과 같습니다. 인증과 월 사용 한도 같은 공통 오류는 오류 코드와 한도에서 확인합니다.

오류의미와 대응
model_not_found (404)에셋 목록에 없는 모델입니다. 대응: 에셋에서 현재 모델 코드와 Chat Completions 지원 여부를 다시 확인합니다.
context_length_exceeded (400)프롬프트와 응답이 모델 컨텍스트 한도를 초과했습니다. 대응: 대화 이력이나 입력을 줄이고 max_tokens를 조정합니다.
tool_format_invalid (400)tools 스키마가 올바르지 않습니다. 대응: 함수 이름과 parameters JSON Schema를 수정합니다.
vision_not_supported (400)선택한 모델이 이미지 입력을 지원하지 않습니다. 대응: 이미지 입력을 제거하거나 지원 모델을 선택합니다.
response_format_not_supported (400)선택한 모델이 JSON 모드 등의 응답 형식을 지원하지 않습니다. 대응: response_format을 제거하거나 지원 모델을 선택합니다.
gateway_timeout (504)비스트리밍 요청에서 응답 대기 시간이 초과됐습니다. 대응: 같은 요청을 자동으로 다시 보내지 않습니다. x-should-retry 헤더와 원래 호출의 비용 판단은 채팅 타임아웃 처리에서 확인합니다.
content_policy_violation (400)콘텐츠 정책으로 요청이 거절됐습니다. 200 응답의 finish_reason: content_filter와 구분합니다. 대응: 같은 요청을 반복하지 말고 입력과 모델의 이용 조건을 확인합니다. 오류 코드와 비용 판단을 따릅니다.
service_unavailable (503)서비스 또는 모델 공급 경로를 이용할 수 없습니다. 이 오류는 보유 유닛 부족과 다릅니다. 대응: 요청 단계별 재시도 기준을 따릅니다.