> ## 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.

# LaoZhang API 연동 가이드: OpenAI·Anthropic·Gemini 요청 보내기

> API 키 설정부터 이미지 생성·편집, 기존 OpenAI 앱 옮기기, 오류 해결까지 동작하는 예제로 따라 할 수 있습니다.

아래 호스트 중 하나로 LaoZhang API 키(콘솔에서는 '토큰'이라고 부릅니다)와 함께 요청을 보냅니다. OpenAI SDK는 base URL로 `https://api.laozhang.ai/v1`을 쓰고, Google Gen AI SDK와 Anthropic SDK는 호스트 루트를 쓰며 나머지 경로는 SDK가 붙입니다.

| 도메인 | 사용하는 경우 |
| - | - |
| `api.laozhang.ai` | 기본값. 이 사이트의 모든 예제가 이 도메인을 사용 |
| `api-vip.laozhang.ai` | 서버가 유럽 또는 북미에 있고 직접 연결하려는 경우 |
| `api2.laozhang.ai` | 네트워크에서 `api.laozhang.ai`에 접속할 수 없는 경우 |

세 도메인은 같은 API 키, 경로, 파라미터를 받으므로 바꿔도 호스트 이름만 달라집니다. 콘솔도 세 도메인 모두에서 열립니다. 애플리케이션이 이미 쓰는 요청 형식을 고른 다음, API 키의 그룹이 호출할 수 있는 모델을 선택하세요.

## API 키 발급

[토큰 관리](https://api.laozhang.ai/token)에서 API 키를 만듭니다. 만들 때 그룹과 과금 방식을 선택하며, 그룹에 따라 키가 호출할 수 있는 모델이 정해집니다.

과금 방식은 사용량 우선(콘솔 표시: 按量优先, 권장)을 선택하세요. 이 방식의 키는 아래 예제에서 쓰는 사용량 과금 텍스트 모델과 호출당 과금 이미지 모델을 모두 호출할 수 있습니다. 두 설정은 [과금, 토큰 그룹, 인보이스](https://docs.laozhang.ai/ko/pricing.md)에서 자세히 설명합니다.

예제를 실행할 터미널에서 키를 환경 변수로 설정합니다.

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

`YOUR_LAOZHANG_API_KEY`는 발급받은 키로 바꾸세요. 키는 서버에만 두고, 브라우저 번들, 소스 저장소, 로그에는 남기지 마세요. 계정 관리용 AccessToken은 별개의 인증 정보이며 [잔액 조회 API](https://docs.laozhang.ai/ko/api-capabilities/balance-query.md) 같은 계정 엔드포인트에서만 씁니다.

예제에서 사용하는 모델은 다음과 같습니다.

* 텍스트: `gpt-5.4-mini`
* Gemini 네이티브 요청: `gemini-3.8-flash`
* Anthropic Messages: `glm-5.2`
* 이미지 생성: `gpt-image-2.5-flare-vip`, 이미지 편집: `gpt-image-2.5-sunburst-vip`

다른 모델을 쓰려면 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에서 정확한 모델 ID를 복사하고, 내 키의 그룹이 그 모델을 호출할 수 있는지 확인하세요. 텍스트 모델과 요청 형식을 고르는 데는 [텍스트 생성 API](https://docs.laozhang.ai/ko/api-capabilities/text-generation.md) 가이드가 도움이 됩니다.

## 텍스트 요청 보내기

Chat Completions는 `messages` 배열을 받습니다. API 키를 Bearer 토큰으로 보내고 본문은 JSON으로 작성합니다.

```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라고만 답하세요"}]
  }'
```

응답은 `choices[0].message.content`에 들어 있고, 이 프롬프트라면 `connected`가 나옵니다. 같은 요청을 애플리케이션에서 쓰려면 메시지 내용만 원하는 프롬프트로 바꾸면 됩니다. 메시지 필드, 스트리밍, 모델별 옵션은 [OpenAI 프로토콜 레퍼런스](https://docs.laozhang.ai/ko/api-reference/chat-completions.md)에서 다룹니다.

## OpenAI SDK

OpenAI SDK가 엔드포인트 경로를 직접 만들기 때문에, base URL은 `/chat/completions` 없이 `https://api.laozhang.ai/v1`까지만 지정합니다.

> [tab] Python
>
> SDK를 설치합니다.
>
> ```bash theme={null}
> python -m pip install openai
> ```
>
> ```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)
> ```

> [tab] Node.js
>
> `npm install openai`로 SDK를 설치한 뒤, 아래 코드를 `.mjs` 파일로 저장하고 Node.js로 실행합니다.
>
> ```javascript theme={null}
> import OpenAI from "openai";
>
> const client = new OpenAI({
>   apiKey: process.env.LAOZHANG_API_KEY,
>   baseURL: "https://api.laozhang.ai/v1",
>   timeout: 120_000,
>   maxRetries: 0,
> });
> const response = await client.chat.completions.create({
>   model: "gpt-5.4-mini",
>   messages: [{ role: "user", content: "connected라고만 답하세요" }],
> });
> console.log(response.choices[0].message.content);
> ```

이 예제들은 SDK의 자동 재시도를 꺼 두었습니다. 요청을 다시 보낼 시점은 애플리케이션이 직접 정하도록 하기 위해서입니다.

같은 클라이언트로 Responses, Images, Audio, Embeddings, Moderations 엔드포인트도 호출할 수 있습니다. OpenAI 모델별 엔드포인트는 `o3-pro`, GPT Image, 음성 모델을 포함해 [LaoZhang API에서 OpenAI 모델 사용하기](https://docs.laozhang.ai/ko/api-reference/openai.md)에 정리되어 있습니다.

### 기존 OpenAI 앱 옮기기

이미 OpenAI SDK를 쓰는 애플리케이션은 세 가지만 바꾸면 됩니다. 클라이언트의 API 키와 base URL(아래 diff 참고), 그리고 각 요청의 `model` 값입니다. 나머지 요청 코드는 그대로 둡니다.

```diff theme={null}
 client = OpenAI(
-    api_key=os.environ["OPENAI_API_KEY"],
+    api_key=os.environ["LAOZHANG_API_KEY"],
+    base_url="https://api.laozhang.ai/v1",
 )
```

SDK를 환경 변수로만 설정하고 있다면 코드를 고치지 않고도 전환할 수 있습니다. OpenAI Python SDK와 Node.js SDK는 `OPENAI_API_KEY`와 `OPENAI_BASE_URL`을 읽습니다.

```bash theme={null}
export OPENAI_API_KEY="$LAOZHANG_API_KEY"
export OPENAI_BASE_URL="https://api.laozhang.ai/v1"
```

운영 트래픽을 보내기 전에 다음을 확인하세요.

* **모델 ID**: OpenAI에서 쓰던 모델 이름이 LaoZhang API에서는 ID나 그룹이 다를 수 있습니다. 정확한 ID는 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에서 복사하세요. OpenAI를 직접 호출할 때와 다른 점은 [OpenAI 모델 가이드](https://docs.laozhang.ai/ko/api-reference/openai.md)에 정리되어 있습니다.
* **선택 파라미터**: 샘플링 옵션, 출력 길이 제한, 구조화된 출력, 도구 설정은 모델마다 다릅니다. 필수 필드만으로 시작해서 필요한 옵션을 하나씩 추가하세요. 지원하지 않는 파라미터라는 오류가 오면 오류가 가리키는 필드를 빼거나 조정합니다.
* **재시도**: 재시도 로직은 한 곳에서만 관리하세요. SDK와 애플리케이션이 모두 재시도하면 사용자 동작 한 번에 API 호출이 여러 번 일어날 수 있습니다.
* **결과 확인**: 위의 최소 요청을 보낸 뒤 [호출 로그](https://api.laozhang.ai/log)에서 해당 요청을 찾아 모델, 토큰 사용량, 청구 금액을 확인하세요.

되돌리려면 이전 API 키와 base URL을 복원하면 됩니다.

## Responses API

Responses API는 요청에 `input`을 넣고 `output` 배열을 반환합니다. 요청 본문이 Chat Completions와 다르므로, 전환하는 애플리케이션은 요청과 응답 파서를 모두 고쳐야 합니다.

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 120 \
>   "https://api.laozhang.ai/v1/responses" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-5.4-mini",
>     "input": "connected라고만 답하세요"
>   }'
> ```

> [tab] Python
>
> 위에서 설치한 `openai` 패키지를 그대로 사용합니다.
>
> ```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.responses.create(
>     model="gpt-5.4-mini",
>     input="connected라고만 답하세요",
> )
> print(response.output_text)
> ```

원본 JSON에서는 `output` 배열 안에서 타입이 `output_text`인 콘텐츠 항목의 `text` 값을 모으면 됩니다. SDK의 `output_text` 헬퍼가 이 작업을 대신해 줍니다. 다른 출력 항목에는 추론 내용이나 도구 호출이 들어 있을 수 있으므로, 첫 번째 항목이 곧 텍스트 답변이라고 가정하면 안 됩니다.

LaoZhang API는 OpenAI의 Responses API를 지원하므로 GPT-6, GPT-5.6, GPT-5.4, `o3-pro` 같은 OpenAI 텍스트 모델에서 사용할 수 있습니다. 다른 제공사의 모델을 이 엔드포인트로 옮기기 전에는 최소 요청을 보내 동작을 확인하세요.

서버 측 대화 상태, `previous_response_id`, 내장 도구도 모델에 따라 지원 여부가 다릅니다. 대화 기록이 필요하면 다음 요청에 필요한 메시지를 애플리케이션에서 직접 보관하세요. 업스트림 필드 정의는 [OpenAI Responses 레퍼런스](https://developers.openai.com/api/reference/resources/responses/methods/create)에, 데이터 처리는 [데이터 정책](https://www.laozhang.ai/data-policy)에 있습니다.

## 이미지 생성 및 편집

두 Images 엔드포인트 모두 `data` 배열을 반환합니다. 모델에 따라 각 항목에는 이미지가 `b64_json`에 Base64로 들어 있거나 `url`에 다운로드 링크로 들어 있습니다.

예제는 GPT Image 2.5 VIP 모델을 사용합니다. 이 모델은 호출당 과금이고, 앞의 텍스트 예제는 사용량 과금입니다. 사용량 우선으로 설정한 키는 둘 다 호출할 수 있습니다. 이미지 요청이 거부되면 키의 [과금 방식](https://docs.laozhang.ai/ko/pricing.md)이 사용량 우선(按量优先) 또는 건당 과금(按次计费)인지 확인하세요.

### 이미지 생성

생성 엔드포인트에 JSON으로 프롬프트를 보냅니다.

```bash theme={null}
curl --fail-with-body --max-time 360 \
  "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare-vip",
    "prompt": "흰 테이블 위에 놓인 파란 세라믹 컵, 부드러운 자연광, 제품 사진."
  }' \
  -o generation.json
```

### 이미지 편집

현재 디렉터리에 `input.png`라는 참조 이미지를 두고, 편집 지시문과 함께 multipart form 데이터로 업로드합니다.

```bash theme={null}
curl --fail-with-body --max-time 360 \
  "https://api.laozhang.ai/v1/images/edits" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-image-2.5-sunburst-vip" \
  -F "image[]=@input.png" \
  -F 'prompt=배경을 연한 파란색으로 바꾸고 피사체는 그대로 유지하세요.' \
  -o edit.json
```

`@` 문법은 파일 내용을 업로드합니다. multipart 콘텐츠 타입과 boundary는 cURL이 설정하도록 두고, 이 요청에는 `Content-Type: application/json`을 추가하지 마세요.

### 결과 저장

응답 파일은 이미지가 아니라 JSON입니다. 아래 스크립트를 `save_images.py`로 저장하세요. Python 표준 라이브러리만 사용합니다.

```python theme={null}
import base64
import json
import re
import sys
import urllib.request
from pathlib import Path

source = Path(sys.argv[1])
response = json.loads(source.read_text())
items = response.get("data") or []
if not items:
    sys.exit(f"{source}에 이미지가 없습니다: {response}")

for index, item in enumerate(items, start=1):
    if item.get("b64_json"):
        # data:image/...;base64, 접두사를 제거하고 부족한 = 패딩을 채웁니다
        encoded = re.sub(r"^data:[^,]*,", "", item["b64_json"].strip())
        raw = base64.b64decode(encoded + "=" * (-len(encoded) % 4))
    elif item.get("url"):
        # 다운로드할 때는 API 키를 보내지 않습니다
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            raw = download.read()
    else:
        continue
    if raw.startswith(b"\x89PNG"):
        extension = "png"
    elif raw.startswith(b"\xff\xd8"):
        extension = "jpg"
    elif raw[:4] == b"RIFF" and raw[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "bin"
    output = source.with_name(f"{source.stem}-{index}.{extension}")
    output.write_bytes(raw)
    print(f"저장했습니다: {output}")
```

두 응답 파일 모두 같은 방식으로 실행합니다.

```bash theme={null}
python save_images.py generation.json
python save_images.py edit.json
```

스크립트는 `data`에 있는 모든 이미지를 `generation-1.png` 같은 이름으로 저장하며, 다음 경우를 처리합니다.

* `data:image/...;base64,` 접두사가 붙어 있거나 끝의 `=` 패딩이 빠진 Base64
* `url` 결과: API 키 없이 내려받습니다. URL 결과는 바로 저장하고 직접 사본을 보관하세요.

두 작업의 Python SDK 예제는 [Images API 레퍼런스](https://docs.laozhang.ai/ko/api-reference/images.md)에 있습니다. 이미지 크기, 품질 설정, 출력 형식은 모델마다 다르므로, 옵션을 추가할 때는 해당 모델 가이드를 따르세요.

## Gemini 네이티브 API 호출

Gemini 네이티브 API는 OpenAI의 messages 대신 `contents[].parts[]` 구조를 씁니다.

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "connected라고만 답하세요"}]
    }]
  }'
```

텍스트는 `candidates[].content.parts[]`의 text 파트에서 읽습니다. 텍스트가 없으면 `finishReason`과 `promptFeedback`을 확인하세요.

Google Gen AI SDK에서는 호스트 루트 `https://api.laozhang.ai`와 `api_version="v1beta"`를 지정합니다. 모델 경로와 API 키 헤더는 SDK가 추가합니다. [Gemini 프로토콜 레퍼런스](https://docs.laozhang.ai/ko/api-reference/gemini.md)에 전체 Python 예제, 두 가지 인증 헤더 방식, 이미지·PDF·오디오 입력 방법이 있습니다. MP4 영상의 프레임과 오디오를 분석하려면 [비디오 이해 API](https://docs.laozhang.ai/en/api-capabilities/video-understanding.md)를 보세요.

## Anthropic Messages API 호출

Anthropic SDK를 비롯해 Anthropic Messages 형식으로 만든 애플리케이션은 `/v1/messages`로 요청을 보냅니다.

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/messages" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "glm-5.2",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "connected라고만 답하세요"}]
  }'
```

* **필수 필드**: `model`, `messages`, `max_tokens`
* **시스템 프롬프트**: `messages`가 아니라 최상위 `system` 필드에 넣습니다.
* **응답**: `content` 배열에는 `text`, `thinking`, `tool_use` 블록이 들어갈 수 있습니다.
* **답변 텍스트**: 첫 번째 블록이 답변이라고 가정하지 말고, `type`이 `text`인 블록을 읽습니다.

Messages 엔드포인트는 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)에서 Anthropic Messages로 표시된 모델을 제공합니다.

* 2026년 10월 18일부터 다시 제공되는 Claude 모델(`claude-sonnet-5-5`, `claude-opus-5-5` 등). Anthropic 자체 API와 다른 점은 [Claude 모델 제한](https://docs.laozhang.ai/ko/api-reference/claude.md)을 참고하세요.
* `glm-5.2`: `default` 토큰 그룹에서 쓸 수 있으며, Anthropic 자체 Messages API의 동작과 매우 가깝습니다.
* `deepseek-v4-pro`, `deepseek-v4-flash`도 이 엔드포인트용으로 표시되어 있습니다.

Anthropic Python SDK에서는 `base_url="https://api.laozhang.ai"`와 LaoZhang API 키를 지정합니다. `/v1/messages`는 SDK가 붙입니다. SDK 사용법, 스트리밍, 도구 호출은 [Claude 프로토콜 레퍼런스](https://docs.laozhang.ai/ko/api-reference/claude.md)에서 다룹니다.

## 그 밖의 API

* [Models API](https://docs.laozhang.ai/en/api-reference/models.md): 애플리케이션에서 쓸 모델 ID 조회
* [임베딩](https://docs.laozhang.ai/en/api-capabilities/text-embedding.md): 텍스트를 벡터로 변환
* [오디오 전사](https://docs.laozhang.ai/en/api-capabilities/audio-transcription.md): 오디오를 업로드하고 전사 텍스트 받기

## 오류 해결

| 상태 코드 | 확인할 것 |
| - | - |
| 400 | JSON 문법, 필드 타입, 모델 옵션, 입력 길이 |
| 401 | API 키, 인증 헤더, 키 만료 여부 |
| 403 | 토큰 그룹, 모델 권한, 계정 제한 |
| 404 | 최종 URL과 정확한 모델 ID. `/v1`이 중복되지 않았는지 확인 |
| 429 | 오류 본문에서 속도, 동시 요청, 용량, 잔액 중 어떤 제한인지 확인 |
| 5xx 또는 타임아웃 | 네트워크 상태, 모델 가용성, 호출 로그 |

잘못된 요청은 고친 뒤에 재시도하세요. 일시적인 장애에는 횟수를 제한한 백오프를 쓰고, SDK 재시도와 애플리케이션 재시도가 겹치지 않게 하세요.

클라이언트 타임아웃이 나도 생성이 취소되는 것은 아니며, 과금 여부도 알 수 없습니다. 이미지 요청을 다시 보내기 전에 [호출 로그](https://api.laozhang.ai/log)를 확인하세요.

문의는 [hi@laozhang.ai](mailto:hi@laozhang.ai) 또는 Telegram [@laozhang\_cn](https://t.me/laozhang_cn)으로 보내 주세요. 요청 시각, 모델, 엔드포인트, 토큰 그룹, 민감 정보를 가린 오류 내용을 함께 알려 주시면 됩니다. 과금과 환불은 [이용약관](https://www.laozhang.ai/terms)을 따릅니다.

## AI 코딩 도구에서 이 문서 사용하기

코딩 어시스턴트에게 대상 모델, 작업 내용, 그리고 아래 파일 중 하나를 알려 주세요.

* [skill.md](https://docs.laozhang.ai/skill.md): 코딩 어시스턴트용 연결 규칙과 최소 요청 모음(영어)
* [llms.txt](https://docs.laozhang.ai/llms.txt)와 [llms-full.txt](https://docs.laozhang.ai/llms-full.txt): 문서의 페이지 색인과 전체 텍스트 내보내기. 현재 둘 다 중국어 문서 기준

인증 정보는 프롬프트에 붙여 넣지 말고 환경 변수로 전달하세요.

## API 레퍼런스

LaoZhang API 레퍼런스입니다.

* [텍스트 생성 API: 프로토콜과 모델 선택](https://docs.laozhang.ai/ko/api-capabilities/text-generation.md)
* [OpenAI 모델: 엔드포인트와 SDK 설정](https://docs.laozhang.ai/ko/api-reference/openai.md)
* [OpenAI 프로토콜: Chat Completions](https://docs.laozhang.ai/ko/api-reference/chat-completions.md)
* [Claude 프로토콜: Anthropic Messages](https://docs.laozhang.ai/ko/api-reference/claude.md)
* [Gemini 프로토콜: generateContent](https://docs.laozhang.ai/ko/api-reference/gemini.md)
* [Images API: 이미지 생성 및 편집](https://docs.laozhang.ai/ko/api-reference/images.md)
* [Models API](https://docs.laozhang.ai/en/api-reference/models.md)

요청 필드와 모델 기능의 기준은 각 제공사의 공식 문서입니다. LaoZhang API의 모델 ID, 이용 가능 여부, 가격은 [모델 및 가격](https://docs.laozhang.ai/ko/models.md)과 [콘솔](https://api.laozhang.ai/account/pricing)에서 확인하세요.

* OpenAI: [API reference](https://developers.openai.com/api/reference/overview), [Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create), [Responses](https://developers.openai.com/api/reference/resources/responses/methods/create), [models](https://developers.openai.com/api/docs/models)
* Anthropic: [Messages API](https://platform.claude.com/docs/en/api/messages)
* Google: [Gemini API 문서](https://ai.google.dev/gemini-api/docs), [generateContent 레퍼런스](https://ai.google.dev/api/generate-content)

Alibaba Cloud, ByteDance, xAI, Black Forest Labs, DeepSeek 등 다른 제공사는 [제공사별 공식 API 문서](https://docs.laozhang.ai/en/resources.md)에서 확인할 수 있으며, 이 페이지는 각 제공사를 해당 LaoZhang API 가이드와 연결해 줍니다.


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