OpenAI 프로토콜: Chat Completions API 호출 방법

OpenAI Chat Completions 하나로 OpenAI, Google Gemini, DeepSeek, Qwen 등 여러 제공사의 텍스트 모델을 호출할 수 있습니다. messages를 보내고 choices[0].message.content에서 답변을 읽으면 됩니다.

항목	내용
엔드포인트	`POST https://api.laozhang.ai/v1/chat/completions`
모델	모델 및 가격의 Endpoints 열에 OpenAI 호환으로 표시된 모델. `model`로 선택합니다
스트리밍	`"stream": true`를 설정하면 답변이 생성되는 대로 받습니다
예제 모델	`gpt-5.4-mini`

선택 파라미터와 도구 지원 여부는 모델마다 다릅니다. 애플리케이션이 Anthropic Messages나 Gemini generateContent 요청 구조로 만들어져 있다면 Claude 프로토콜 또는 Gemini 프로토콜 페이지를 보세요. 세 형식은 텍스트 생성 API 가이드에서 비교합니다.

POST https://api.laozhang.ai/v1/chat/completions

요청 보내기

토큰 관리에서 과금 방식을 사용량 우선(콘솔 표시: 按量优先, 권장) 또는 사용량 과금(按量计费)으로 설정해 API 키(콘솔에서는 ‘토큰’이라고 부릅니다)를 만들고, 터미널에서 환경 변수로 설정하세요.

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"

요청은 Authorization: Bearer 인증을 쓰고, 본문은 model과 messages가 들어 있는 JSON입니다. 예제는 gpt-5.4-mini를 사용합니다.

cURL
Python

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "connected라고만 답하세요"}
    ]
  }'

python -m pip install openai로 SDK를 설치하세요.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "connected라고만 답하세요"}],
)
print(response.choices[0].message.content)

이 프롬프트의 답변은 connected여야 합니다. 클라이언트 설정이 끝났다면 프롬프트를 애플리케이션의 메시지로 바꾸세요.

모델 고르기

모델은 모델 및 가격에서 고르세요. model 값을 바꾸기 전에 해당 모델 행에서 세 가지를 확인합니다.

Endpoints에 OpenAI 호환이 포함되어 있는지. o3-pro 계열처럼 Responses만 표시된 모델은 /v1/responses를 써야 합니다. API 연동 가이드의 Responses API 예제를 참고하세요.
Token groups에 내 API 키의 그룹이 포함되어 있는지.
100만 토큰당 Input, Output, Cache read 가격이 워크로드에 맞는지.

카탈로그에 있는 대표적인 텍스트 모델입니다.

gpt-5.4-mini, gpt-5.4
gemini-3.8-flash, gemini-3.6-flash, gemini-3.5-flash-lite

제품 이름으로 ID를 조합하지 말고 카탈로그나 콘솔에서 정확한 ID를 복사하세요. 이 모델들의 형식과 가격은 텍스트 생성 API 가이드에 있고, Responses 전용인 o3-pro를 호출하는 방법은 OpenAI 모델에 있습니다. 일반적인 순위표만으로는 내 애플리케이션에 맞는 모델을 알 수 없습니다. 실제 프롬프트 샘플을 후보 모델 두세 개에 보내 답변 품질, 지시 따르기, 구조화된 출력, 도구를 쓴다면 도구 호출 성공률, 지연 시간, 요청별로 기록되는 토큰 사용량을 비교하세요. 선택한 모델 ID는 설정 파일에 고정해, 모델 변경이 의도한 업데이트가 되게 하세요.

요청 필드

필드	설명
`model`	필수. 내 토큰 그룹에서 쓸 수 있는 정확한 모델 ID
`messages`	필수. 대화 순서대로 정렬한 메시지
`stream`	선택. `true`이면 답변을 서버 전송 이벤트(SSE)로 반환합니다. 아래 응답 스트리밍 절 참고
`temperature`, `top_p`	선택. 모델이 지원하는 경우의 샘플링 제어
`max_completion_tokens`	이 필드를 받는 모델의 출력 제한
`max_tokens`	일부 모델이 쓰는 출력 제한. 두 제한 필드를 함께 보내지 마세요
`response_format`	JSON 또는 구조화된 출력을 지원하는 모델의 출력 형식 설정
`tools`, `tool_choice`	도구 호출을 지원하는 모델의 도구 정의와 선택 설정

model과 messages만으로 시작하세요. 선택 필드와 허용 값은 모델마다 달라서, 지원하지 않는 파라미터 때문에 거부된 요청은 필드를 고친 뒤에 다시 보내야 합니다. 업스트림 필드 정의는 OpenAI Chat Completions 공식 레퍼런스를 참고하세요.

메시지와 대화 기록

각 메시지에는 role과 content가 있습니다. 사용자 입력에는 user를, 이전 모델 답변에는 assistant를 씁니다. 애플리케이션에 필요한 대화 기록을 요청마다 함께 보내세요.

[
  {"role": "user", "content": "내 프로젝트 이름은 Cedar입니다."},
  {"role": "assistant", "content": "Cedar 프로젝트를 어떻게 도와드릴까요?"},
  {"role": "user", "content": "Cedar에 어울리는 짧은 태그라인을 제안해 주세요."}
]

system이나 developer 같은 지시 역할, 도구 메시지, 멀티모달 콘텐츠는 선택한 모델에 따라 지원 여부가 다릅니다. 비전 모델에 이미지를 보내려면 이미지 이해 API를 보세요.

응답 읽기

텍스트 응답에는 choices 배열이 들어 있습니다. 아래는 읽어야 할 필드만 줄인 예시입니다.

{
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "connected"},
      "finish_reason": "stop"
    }
  ]
}

답변은 message.content에서, 생성이 끝난 이유는 finish_reason에서 읽습니다. finish_reason이 length이면 출력 또는 컨텍스트 제한에 도달했다는 뜻입니다. 완전한 답변이 필요하면 입력을 줄이거나 모델이 지원하는 출력 제한을 조정하세요. 도구 호출을 지원하는 모델은 일반 텍스트 대신 message.tool_calls를 반환할 수 있습니다. 대화를 이어 갈 때는 이 호출과 그에 대응하는 결과를 그대로 보존하세요. 토큰 수는 usage에 나타날 수 있으며, 계정에 청구된 금액은 호출 로그에서 확인하세요.

응답 스트리밍

"stream": true를 추가하면 모델이 쓰는 대로 답변을 조각으로 받습니다. 응답은 서버 전송 이벤트(SSE) 스트림입니다.

각 data: 줄에 chat.completion.chunk 객체가 담깁니다.
새 텍스트는 choices[0].delta.content에 있습니다.
스트림은 data: [DONE] 줄로 끝납니다.

cURL
Python

-N은 cURL의 출력 버퍼링을 꺼서 각 청크가 도착하는 즉시 출력되게 합니다.

curl --fail-with-body -N --max-time 300 \
  "https://api.laozhang.ai/v1/chat/completions" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "stream": true,
    "messages": [
      {"role": "user", "content": "변수 이름을 짓는 요령 세 가지를 짧게 알려 주세요."}
    ]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=300.0,
    max_retries=0,
)
stream = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "변수 이름을 짓는 요령 세 가지를 짧게 알려 주세요."}],
    stream=True,
)
for chunk in stream:
    if not chunk.choices:
        continue
    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)
print()

원본 스트림은 다음과 같습니다. 필요한 필드만 남겼으며 실제 청크에는 id, model 같은 필드도 있습니다.

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1. 변수 이름은"},"finish_reason":null}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

스트림을 읽을 때는 다음을 지키세요.

delta.content를 순서대로 이어 붙이면 전체 답변이 됩니다.
첫 청크에는 역할만 있을 수 있고, 마지막 사용량 청크처럼 choices 배열이 비어 있는 청크도 있으므로 읽기 전에 확인하세요.
마지막 콘텐츠 청크에 finish_reason이 설정되고, 이어서 data: [DONE]이 스트림을 닫습니다. Python SDK는 이 시점에 루프를 끝냅니다.
[DONE] 전에 연결이 끊기면 답변이 불완전한 것으로 처리하세요.

오류 처리

상태	조치
400	잘못된 필드, 필드 타입, 모델 제한을 넘는 입력을 고치세요.
401	Bearer 헤더와 API 키를 확인하세요.
403	토큰 그룹 권한과 계정 제한을 확인하세요.
404	엔드포인트와 정확한 모델 ID를 확인하세요.
429	오류 본문에서 속도, 동시 요청, 용량, 잔액 제한 중 무엇인지 확인하세요.
5xx	호출 로그를 확인하고 일시적인 오류는 제한된 백오프로 재시도하세요.

클라이언트 타임아웃이 났다면 요청을 다시 보내기 전에 호출 로그에서 해당 요청이 기록되었는지 확인하세요. Python 예제는 자동 재시도를 꺼 두었으므로, 재시도는 애플리케이션에서 의도적으로 추가하세요. 고객 지원에 문의할 때는 요청 시각, 엔드포인트, 모델, 토큰 그룹, 인증 정보를 지운 오류 메시지를 함께 보내세요. API 키는 절대 보내지 마세요.

시작하기

이미지 생성·편집 API

비디오 생성 API

텍스트 API

OpenAI 프로토콜: Chat Completions API 호출 방법

요청 보내기

모델 고르기

요청 필드

메시지와 대화 기록

응답 읽기

응답 스트리밍

오류 처리

관련 문서

​요청 보내기

​모델 고르기

​요청 필드

​메시지와 대화 기록

​응답 읽기

​응답 스트리밍

​오류 처리

​관련 문서

요청 보내기

모델 고르기

요청 필드

메시지와 대화 기록

응답 읽기

응답 스트리밍

오류 처리

관련 문서