> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> OpenAI Chat Completions 형식으로 LaoZhang API의 텍스트 모델을 호출합니다. cURL·Python 예제, 스트리밍, 응답 필드, 오류 처리를 다룹니다.

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

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

선택 파라미터와 도구 지원 여부는 모델마다 다릅니다. 애플리케이션이 Anthropic Messages나 Gemini `generateContent` 요청 구조로 만들어져 있다면 [Claude 프로토콜](https://docs.laozhang.ai/ko/api-reference/claude.md) 또는 [Gemini 프로토콜](https://docs.laozhang.ai/ko/api-reference/gemini.md) 페이지를 보세요. 세 형식은 [텍스트 생성 API](https://docs.laozhang.ai/ko/api-capabilities/text-generation.md) 가이드에서 비교합니다.

```text theme={null}
POST https://api.laozhang.ai/v1/chat/completions
```

## 요청 보내기

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

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

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

> [tab] cURL
>
> ```bash theme={null}
> 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라고만 답하세요"}
>     ]
>   }'
> ```

> [tab] Python
>
> `python -m pip install openai`로 SDK를 설치하세요.
>
> ```python theme={null}
> 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`여야 합니다. 클라이언트 설정이 끝났다면 프롬프트를 애플리케이션의 메시지로 바꾸세요.

## 모델 고르기

모델은 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에서 고르세요. `model` 값을 바꾸기 전에 해당 모델 행에서 세 가지를 확인합니다.

* **Endpoints**에 OpenAI 호환이 포함되어 있는지. `o3-pro` 계열처럼 Responses만 표시된 모델은 `/v1/responses`를 써야 합니다. [API 연동 가이드](https://docs.laozhang.ai/ko/api-manual.md)의 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](https://docs.laozhang.ai/ko/api-capabilities/text-generation.md) 가이드에 있고, Responses 전용인 `o3-pro`를 호출하는 방법은 [OpenAI 모델](https://docs.laozhang.ai/ko/api-reference/openai.md)에 있습니다.

일반적인 순위표만으로는 내 애플리케이션에 맞는 모델을 알 수 없습니다. 실제 프롬프트 샘플을 후보 모델 두세 개에 보내 답변 품질, 지시 따르기, 구조화된 출력, 도구를 쓴다면 도구 호출 성공률, 지연 시간, 요청별로 기록되는 토큰 사용량을 비교하세요.

선택한 모델 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 공식 레퍼런스](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)를 참고하세요.

### 메시지와 대화 기록

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

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

`system`이나 `developer` 같은 지시 역할, 도구 메시지, 멀티모달 콘텐츠는 선택한 모델에 따라 지원 여부가 다릅니다. 비전 모델에 이미지를 보내려면 [이미지 이해 API](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md)를 보세요.

## 응답 읽기

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

```json theme={null}
{
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "connected"},
      "finish_reason": "stop"
    }
  ]
}
```

답변은 `message.content`에서, 생성이 끝난 이유는 `finish_reason`에서 읽습니다. `finish_reason`이 `length`이면 출력 또는 컨텍스트 제한에 도달했다는 뜻입니다. 완전한 답변이 필요하면 입력을 줄이거나 모델이 지원하는 출력 제한을 조정하세요.

도구 호출을 지원하는 모델은 일반 텍스트 대신 `message.tool_calls`를 반환할 수 있습니다. 대화를 이어 갈 때는 이 호출과 그에 대응하는 결과를 그대로 보존하세요. 토큰 수는 `usage`에 나타날 수 있으며, 계정에 청구된 금액은 [호출 로그](https://docs.laozhang.ai/en/faq/call-logs.md)에서 확인하세요.

## 응답 스트리밍

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

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

> [tab] cURL
>
> `-N`은 cURL의 출력 버퍼링을 꺼서 각 청크가 도착하는 즉시 출력되게 합니다.
>
> ```bash theme={null}
> 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": "변수 이름을 짓는 요령 세 가지를 짧게 알려 주세요."}
>     ]
>   }'
> ```

> [tab] Python
>
> ```python theme={null}
> 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` 같은 필드도 있습니다.

```text theme={null}
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 | 호출 로그를 확인하고 일시적인 오류는 제한된 백오프로 재시도하세요. |

클라이언트 타임아웃이 났다면 요청을 다시 보내기 전에 [호출 로그](https://api.laozhang.ai/log)에서 해당 요청이 기록되었는지 확인하세요. Python 예제는 자동 재시도를 꺼 두었으므로, 재시도는 애플리케이션에서 의도적으로 추가하세요.

고객 지원에 문의할 때는 요청 시각, 엔드포인트, 모델, 토큰 그룹, 인증 정보를 지운 오류 메시지를 함께 보내세요. API 키는 절대 보내지 마세요.

## 관련 문서

* [텍스트 생성 API: 프로토콜과 모델](https://docs.laozhang.ai/ko/api-capabilities/text-generation.md)
* [LaoZhang API에서 OpenAI 모델 사용하기](https://docs.laozhang.ai/ko/api-reference/openai.md)
* [API 연동 가이드](https://docs.laozhang.ai/ko/api-manual.md)
* [모델 및 가격](https://docs.laozhang.ai/ko/models.md)
* [이미지 이해 API](https://docs.laozhang.ai/en/api-capabilities/vision-understanding.md)
* [Models API](https://docs.laozhang.ai/en/api-reference/models.md)
* [모델 사용 가능 여부와 권한](https://docs.laozhang.ai/en/faq/model-availability.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.