Chat Completions

지원 모델에 대화를 보내고 OpenAI 호환 응답을 받으세요.

대화는 messages 배열로 보내며 이미지 입력과 도구 호출은 선택한 모델의 지원 범위를 따릅니다.

POSThttps://gw.letsur.ai/v1/chat/completions

AUTHAuthorization: Bearer <API_KEY>

요청 필드

필드	타입	요구 여부	기본값	설명
`model`	string	필수	—	모델 코드 (에셋)
`messages`	array	필수	—	`{role, content}` 객체의 배열
`temperature`	number	선택	`1`	0 ~ 2
`top_p`	number	선택	`1`	누적 확률을 기준으로 다음 토큰 후보를 고르는 설정
`max_tokens`	integer	선택	모델별	응답 최대 토큰
`stream`	boolean	선택	`false`	Server-Sent Events 스트리밍
`stream_options`	object	선택	—	`include_usage: true`로 마지막 사용량 요약을 요청합니다
`stop`	string \| array	선택	—	응답 중단 시퀀스
`n`	integer	선택	`1`	응답 개수 (대부분 1)
`tools`	array	선택	—	도구 호출 정의
`tool_choice`	string \| object	선택	`auto`	도구 선택 방식
`response_format`	object	선택	—	JSON 모드 등

모델별 지원 파라미터

이미지 입력, 도구 호출, JSON 모드, 스트리밍의 지원 여부와 세부 제한은 모델마다 다릅니다.

정확한 지원 여부는 에셋의 모델 상세에서 확인합니다. 지원하지 않는 파라미터를 포함한 요청은 실패할 수 있습니다.

`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_reason`	`stop` / `length` / `tool_calls` / `content_filter` (finish_reason 별 의미)
`estimated_cost`	비스트리밍 응답 최상위의 호출별 비용 객체입니다. 이름에는 `estimated`가 남아 있지만 과금 기록에 사용한 같은 비용 값을 반환합니다 (요금)

`finish_reason`

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

값	의미	대응
`stop`	모델이 응답 생성을 끝냈습니다	응답 내용을 확인하고 애플리케이션에 필요한 형식과 조건을 만족하는지 검사합니다
`length`	`max_tokens` 또는 모델 컨텍스트 한도에 걸려 잘렸습니다	`max_tokens`을 키우거나, 같은 프롬프트로 이어 받습니다 (대화 컨텍스트에 부분 응답을 포함해 재요청)
`tool_calls`	모델이 도구 호출을 요청했습니다. 응답 본문 대신 `tool_calls` 필드를 봅니다	도구 호출 흐름으로 진입합니다
`content_filter`	공급사 안전 필터가 응답을 차단했습니다	응답에 제공된 설명과 모델의 입력 조건을 확인합니다. 같은 요청을 자동 반복하지 않고 필요한 입력을 수정한 뒤 다시 요청할지 판단합니다

finish_reason이 content_filter라면 응답 본문은 비거나 짧을 수 있습니다. 클라이언트에서 이 경우를 별도로 처리합니다.

요청과 응답 예시

아래 예제는 Bash 또는 서버 runtime의 LETSUR_API_KEY 환경 변수를 읽습니다. 키 설정과 첫 실행은 AI 게이트웨이 시작하기에서 확인합니다.

cURL


(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/chat/completions \
    --header @- \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "messages": [{"role": "user", "content": "안녕"}]
    }' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

Python


import os
 
from openai import OpenAI
 
client = OpenAI(api_key=os.environ["LETSUR_API_KEY"], base_url="https://gw.letsur.ai/v1")
 
response = client.chat.completions.create(
    model="<MODEL_CODE>",
    messages=[{"role": "user", "content": "안녕"}],
)

TypeScript


import OpenAI from "openai";
 
const apiKey = process.env.LETSUR_API_KEY;
if (!apiKey) throw new Error("LETSUR_API_KEY가 필요합니다.");
 
const client = new OpenAI({
  apiKey,
  baseURL: "https://gw.letsur.ai/v1",
});
 
const response = await client.chat.completions.create({
  model: "<MODEL_CODE>",
  messages: [{ role: "user", content: "안녕" }],
});

스트리밍

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


(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/chat/completions \
    --header @- \
    -H "Content-Type: application/json" \
    -d '{
      "model": "<MODEL_CODE>",
      "messages": [{"role": "user", "content": "안녕"}],
      "stream": true,
      "stream_options": {"include_usage": true}
    }' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

다음은 텍스트가 들어오는 응답 조각부터 보여 주는 설명용 예시입니다.


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] 수신 여부를 기록하고, 받지 못한 출력은 부분 응답으로 취급합니다.

오류 응답을 받았다면 HTTP 상태와 type, error_ref를 기록하고 오류 코드의 기준으로 처리합니다. 연결이 종료됐다는 이유만으로 같은 요청을 즉시 반복하지 않습니다.

이미지 입력

지원 모델에서는 이미지를 입력으로 보낼 수 있습니다.


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,..."}}`

이미지 크기와 해상도 제한은 모델마다 다릅니다. 에셋의 모델 상세에서 확인합니다.

이미지 생성 결과

에셋에서 제공 중인 Gemini 이미지 모델은 별도의 Images API가 아니라 POST /v1/chat/completions로 호출합니다. 일반 Chat Completions 요청처럼 messages에 프롬프트를 보내며, 생성된 이미지는 choices[0].message.images[]에 들어옵니다.


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

현재 사용할 수 있는 Gemini 이미지 모델 코드는 에셋에서 확인합니다. gpt-image-2를 사용할 때는 Image Generations를 따릅니다.

도구 호출

함수 도구 호출은 모델이 실행할 함수 이름과 인수를 응답으로 요청하는 방식입니다. 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에 들어 있습니다. 위 예제는 호출 요청을 받는 단계까지 보여 줍니다. 실제 함수는 클라이언트 코드가 실행하고 결과를 role: "tool" 메시지로 다음 요청에 넣습니다. 여러 도구를 호출했다면 각 결과를 원래 호출 식별자와 대응시켜야 합니다.

`tool_choice`	의미
`"auto"` (기본)	모델이 판단합니다
`"none"`	도구를 호출하지 않습니다
`"required"`	모델이 도구 호출을 요청하도록 지정합니다. 실제 실행은 클라이언트가 처리합니다
`{"type": "function", "function": {"name": "..."}}`	모델이 호출을 요청할 함수를 지정합니다

도구 호출 지원 여부와 요청 형식은 모델마다 다릅니다. 현재 지원 범위는 에셋에서 확인합니다.

오류와 복구

이 엔드포인트 문맥에서 자주 확인할 오류를 표시합니다. 인증과 월 사용 한도 같은 공통 오류는 오류 코드와 한도에서 확인합니다.

오류	의미와 대응
`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`을 제거하거나 지원 모델을 선택합니다.