텍스트 생성 API: OpenAI·Claude·Gemini 프로토콜

​

프로토콜 선택

• 새 프로젝트, 또는 OpenAI SDK나 OpenAI 형식 기반 클라이언트: OpenAI 호환 Chat Completions를 쓰세요. OpenAI 프로토콜 레퍼런스를 참고하세요.
• Anthropic SDK, Claude Code, 기타 Messages 클라이언트: Anthropic Messages를 쓰세요. Claude 프로토콜 레퍼런스를 참고하세요.
• Google Gen AI SDK, 또는 Gemini 네이티브 필드에 의존하는 코드: Gemini 형식을 쓰세요. Gemini 프로토콜 레퍼런스를 참고하세요.

OpenAI 호환          POST https://api.laozhang.ai/v1/chat/completions
Anthropic Messages   POST https://api.laozhang.ai/v1/messages
Gemini 네이티브      POST https://api.laozhang.ai/v1beta/models/{model}:generateContent

• 2026년 10월 18일부터 다시 제공되는 Claude 모델. 전환하기 전에 Claude 모델 제한을 확인하세요.
• glm-5.2(default 토큰 그룹)
• deepseek-v4-pro
• deepseek-v4-flash

​

주요 텍스트 모델

• GPT-6 모델, GPT-5.6 모델, gpt-5.4, claude-haiku-5-5는 긴 입력에 더 높은 구간 가격을 부과합니다. 기준값과 가격은 모델 및 가격의 구간별 가격 표에 있습니다.
• GPT-6 세 모델 중 고르는 방법과 Chat Completions에서의 파라미터·도구 호출에 대한 OpenAI 규칙은 GPT-6 출시 공지를 참고하세요.
• 표의 OpenAI 모델은 Responses 엔드포인트 POST /v1/responses에서도 쓸 수 있으며 o3-pro 계열은 Responses만 지원합니다.
• GPT-6 Astra와 GPT-6.1 Sol의 도구 호출은 Responses가 필요합니다. GPT-6.1 Sol의 다른 파라미터 차이는 GPT-6.1 Sol 출시 공지를, 예제는 LaoZhang API에서 OpenAI 모델 사용하기를 참고하세요.
• Gemini 4 Argon이 깊이 추론해야 한다면 high 사고 수준을 보내세요. 사고 수준과 출시 가격은 Gemini 4 Argon 출시 공지를 참고하세요.
• 비전 모델에 이미지를 보내려면 이미지 이해 API를 참고하세요.

​

첫 요청 보내기

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"

• Python: python -m pip install openai를 실행합니다.
• Node.js: npm install openai를 실행하고, 코드를 chat.mjs로 저장한 뒤 node chat.mjs로 실행합니다.

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

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)

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);

​

응답 스트리밍

• OpenAI 호환: choices[0].delta.content를 순서대로 이어 붙이고, choices나 content가 없는 청크는 건너뜁니다. 스트림은 data: [DONE]으로 끝납니다. 전체 cURL·Python 예제와 원본 이벤트는 OpenAI 프로토콜 레퍼런스의 스트리밍 절에 있습니다.
• Anthropic Messages: 텍스트는 content_block_delta 이벤트의 delta.text로 도착하며 message_stop이 와야 응답이 완료된 것입니다. Claude 프로토콜 레퍼런스를 참고하세요.
• Gemini 네이티브: generateContent를 streamGenerateContent로 바꾸고 ?alt=sse를 붙입니다. 각 이벤트에 candidates가 들어 있는 부분 응답이 실립니다. Gemini 프로토콜 레퍼런스를 참고하세요.
• 종료 표시가 오기 전에 연결이 닫히면 받은 텍스트는 불완전한 것입니다. 요청을 실패로 처리하거나 다시 보내세요. cURL에서는 출력 버퍼링을 끄도록 -N을 추가하세요.

​

자주 만나는 오류 해결

• URL에 /v1/v1이 있는 404: SDK base URL이 경로 일부를 중복합니다. OpenAI SDK는 https://api.laozhang.ai/v1, Anthropic·Google Gen AI SDK는 https://api.laozhang.ai를 쓰세요.
• 모델을 쓸 수 없음, 403, 404: 카탈로그에서 정확한 모델 ID를 복사하고, 내 키의 토큰 그룹에 그 모델이 포함되는지, 모델이 보내는 형식을 지원하는지 확인하세요. 예를 들어 o3-pro는 Responses로만, gpt-6-astra의 도구 호출은 Responses로만 동작하며 GPT 모델은 Gemini 네이티브 요청을 받지 않습니다. 모델 이용 가능 여부를 참고하세요.
• 400: Messages 요청에 max_tokens가 없는 경우가 흔합니다. 그렇지 않다면 최소 요청으로 돌아가 선택 필드를 하나씩 추가하면서, 오류가 가리키는 필드를 고치세요.
• 401: API 키가 틀렸거나, 헤더 형식이 잘못되었거나, 현재 셸에 환경 변수가 설정되지 않았습니다.
• 빈 응답:
  • Chat Completions: message.tool_calls와 finish_reason을 확인합니다.
  • Messages: content[0]을 쓰지 말고 content[]를 블록 type별로 읽습니다.
  • Gemini: finishReason과 promptFeedback을 확인합니다.
• 잘린 응답: 아래 값 중 하나라면 응답이 출력 한도에 걸린 것입니다. 모델의 출력 한도를 늘리거나 입력을 줄이세요.
  • Chat Completions: finish_reason이 length
  • Messages: stop_reason이 max_tokens
  • Gemini: finishReason이 MAX_TOKENS
• 429: 오류 본문을 읽고 속도·동시 요청 제한과 잔액 부족을 구분하세요. 잔액이 남아 있다면 잔액이 남았는데 실패하는 이유를 참고하세요.

​

운영 배포 전 점검

1. 모델 ID와 프로토콜을 설정에 고정하고, 모델 변경도 다른 릴리스처럼 테스트하세요.
2. 내 프롬프트 샘플을 후보 모델 두세 개에 돌려 응답 품질, 지연 시간, 토큰 사용량을 비교하세요. 비교 방법은 OpenAI 프로토콜 레퍼런스의 모델 선택 절에 있습니다.
3. 일반 요청, 스트리밍, 오류 처리를 테스트하세요. 재시도는 SDK와 애플리케이션 중 한 계층에서만 관리합니다.
4. 호출 로그에서 요청별 모델, 입력·출력 토큰, 청구액을 확인하세요.

​

관련 문서

• OpenAI 프로토콜: Chat Completions
• LaoZhang API에서 OpenAI 모델 사용하기
• Claude 프로토콜: Anthropic Messages
• Gemini 프로토콜: generateContent
• API 연동 가이드: 키, base URL, Responses, 이미지
• 모델 및 가격
• 업스트림 문서: OpenAI 텍스트 생성, Anthropic Messages API, Gemini 텍스트 생성