GLM-5.3-Flash는 OpenAI 호환 API를 제공합니다. 기존 클라이언트에서 기본 URL과 모델 문자열만 바꾸면 빠르게 통합할 수 있으며, GLM-5 계열 최초로 텍스트 요청 내 이미지 입력도 지원합니다.
이 글에서는 API 키 발급, 텍스트·이미지 호출, 추론 노력 설정, 스트리밍, 도구 호출, 오류 처리와 비용 확인을 다룹니다. 모든 예제의 모델 ID는 glm-5.3-flash입니다.
모델의 배경이 필요하다면 GLM-5.3-Flash 설명서를 먼저 확인하세요. 더 큰 모델을 사용 중이라면 GLM-5.3 API 가이드를 참고하세요. 두 모델은 모델 ID, 요금, 이미지 입력 경로가 다릅니다.
API 키 발급
z.ai에서 계정을 만들고 대시보드의 API 키 섹션에서 키를 생성합니다. 키는 코드가 아닌 환경 변수에 저장하세요.
export ZAI_API_KEY="your-key-here"
표준 API 기본 URL은 다음과 같습니다.
https://api.z.ai/api/paas/v4/
Claude Code 또는 Cline에 연결할 때는 코딩 플랜용 별도 기본 URL이 필요할 수 있습니다. 설정 방법은 Claude Code 및 Cline 가이드를 참고하세요.
첫 번째 호출
공식 OpenAI SDK를 그대로 사용할 수 있습니다.
from openai import OpenAI
import os
client = OpenAI(
[REDACTED CREDENTIAL]ZAI_API_KEY"],
base_url="https://api.z.ai/api/paas/v4/",
)
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[
{"role": "user", "content": "Explain what a KV cache is in two sentences."}
],
)
print(response.choices[0].message.content)
curl 호출도 동일합니다.
curl https://api.z.ai/api/paas/v4/chat/completions \
-H "[REDACTED CREDENTIAL] $ZAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3-flash",
"messages": [
{"role": "user", "content": "Explain what a KV cache is in two sentences."}
]
}'
Node.js에서는 다음과 같이 호출합니다.
import OpenAI from "openai";
const client = new OpenAI({
[REDACTED CREDENTIAL],
baseURL: "https://api.z.ai/api/paas/v4/",
});
const response = await client.chat.completions.create({
model: "glm-5.3-flash",
messages: [
{ role: "user", content: "Explain what a KV cache is in two sentences." },
],
});
console.log(response.choices[0].message.content);
기본 URL과 모델 ID 외에는 GLM 전용 코드가 거의 없습니다. 따라서 실제 워크로드에서 모델 교체 비용을 낮추고 쉽게 벤치마킹할 수 있습니다.
이미지 전송
GLM-5.3-Flash의 이미지 입력은 콘텐츠 블록으로 전달합니다. content를 문자열 대신 유형이 지정된 배열로 지정하세요.
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "This screenshot shows a rendering bug. What is wrong with the layout?",
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/screenshots/broken-layout.png"
},
},
],
}
],
)
적용할 규칙은 세 가지입니다.
이미지 URL은 공개 URL 또는 base64 데이터 URL이어야 합니다. 로컬 또는 비공개 이미지는 인코딩합니다.
import base64
with open("broken-layout.png", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
image_block = {
"type": "image_url",
"image_url": {"url": f"data:image/png;base64,{encoded}"},
}
여러 이미지는 여러 블록으로 전달합니다. URL 배열 단축 형식은 없습니다. 디자인과 구현 결과를 비교하려면 동일한 콘텐츠 배열에 image_url 블록을 각각 넣으세요.
content = [
{"type": "text", "text": "Does the second image match the design in the first?"},
{"type": "image_url", "image_url": {"url": design_data_url}},
{"type": "image_url", "image_url": {"url": built_data_url}},
]
콘텐츠 순서도 중요합니다. 모델은 배열을 순서대로 읽습니다. 작업을 설명하는 텍스트를 이미지보다 먼저 두세요. 예를 들어 질문 뒤에 비교할 이미지 두 개를 배치하는 편이 더 명확합니다.
Z.ai 문서에는 같은 콘텐츠 블록 방식을 사용하는 비디오와 파일 입력도 나와 있습니다. 비디오 입력은 이미지보다 새롭고 사용 사례가 적으므로, 기능화하기 전에 실제 미디어로 검증하세요.
스크린샷-코드 워크플로와 1M 토큰 컨텍스트에서 긴 문서·이미지를 함께 사용하는 방법은 GLM-5.3-Flash 비전 가이드를 참고하세요.
추론 노력 제어
reasoning_effort로 세 가지 사고 모드를 설정할 수 있습니다.
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "Refactor this function for clarity."}],
extra_body={"reasoning_effort": "low"},
)
허용 값은 low, high, max이며, 기본값은 max입니다. 대량 분류나 추출처럼 깊은 추론이 필요 없는 작업은 low를 명시하면 출력 토큰 사용량을 크게 줄일 수 있습니다.
GLM-5.2는 high와 max만 제공했습니다. low는 비용 민감한 배치 작업에 특히 유용한 새 옵션입니다.
reasoning_effort는 표준 OpenAI 스키마가 아니므로 Python SDK에서는 extra_body에 넣어야 합니다. raw curl 요청에서는 최상위 필드로 보냅니다.
권장 샘플링 매개변수
Z.ai는 작업 유형별 기본값을 다음과 같이 제시합니다.
| 사용 사례 | temperature | top_p |
|---|---|---|
| 일반 | 1.0 | 0.95 |
| 코딩 | 0.95 | 1.0 |
두 프로필의 차이는 작지만, 코드 출력이 일관되지 않다면 코딩 프로필을 적용해 보세요.
스트리밍
표준 OpenAI 스트리밍 방식으로 처리합니다.
stream = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "Write a bash script that rotates logs."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
Artificial Analysis에 따르면 GLM-5.3-Flash는 초당 약 49토큰을 생성하며, GLM-5.3의 약 86토큰보다 느립니다. 첫 토큰 응답 시간은 약 1.52초입니다. 따라서 UI 스트리밍에는 적합하지만, 긴 문서를 생성하는 배치 작업에서는 생성 시간을 예산에 반영해야 합니다.
도구 호출
도구 정의는 표준 OpenAI 스키마를 사용합니다.
tools = [
{
"type": "function",
"function": {
"name": "get_deployment_status",
"description": "Returns the current status of a named deployment.",
"parameters": {
"type": "object",
"properties": {
"service": {
"type": "string",
"description": "The service name, for example 'checkout-api'.",
}
},
"required": ["service"],
},
},
}
]
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[{"role": "user", "content": "Is checkout-api healthy?"}],
tools=tools,
)
call = response.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)
Z.ai가 발표한 에이전트 벤치마크에서 AutomationBench 점수는 GLM-5.2의 26.2점 대비 48.8점입니다. 공급업체 수치이지만, 단일 턴 채팅보다 도구 호출 루프에 모델이 최적화됐다는 방향성과 일치합니다.
기존 API에서 도구 정의를 생성하려면 OpenAPI 사양을 에이전트 도구로 전환하는 방법을 참고하세요.
반드시 구현할 오류 처리
프로덕션에서 주로 마주치는 실패 유형은 세 가지입니다.
요청 속도 제한: 지수 백오프와 지터를 사용해 재시도하세요. 여러 워커가 고정 간격으로 재시도하면 동기화된 재시도가 발생해 제한 상태가 길어질 수 있습니다.
import time, random
from openai import RateLimitError
def call_with_retry(**kwargs):
for attempt in range(5):
try:
return client.chat.completions.create(**kwargs)
except RateLimitError:
if attempt == 4:
raise
time.sleep((2 ** attempt) + random.random())
컨텍스트 오버플로: 1M 토큰 컨텍스트라도 긴 문서와 고해상도 이미지 몇 장으로 초과할 수 있습니다. 이미지는 컨텍스트 예산을 소비하며, 오류는 프롬프트 조립 시점이 아닌 요청 시점에 발생합니다. 입력 토큰 예산을 추적하세요.
잘린 출력: 응답이 문장 중간에 끝나면 finish_reason을 확인하세요. 값이 length라면 모델이 포기한 것이 아니라 출력 한도에 도달한 것입니다. 최대 출력 토큰 수는 출처마다 다르므로 명시적으로 확인해야 합니다.
토큰 사용량 확인
응답의 usage 객체가 실제 호출 비용을 확인하는 가장 신뢰할 수 있는 정보입니다.
print(response.usage.prompt_tokens, response.usage.completion_tokens)
특히 완료 토큰을 추적하세요. reasoning_effort가 기본값인 max일 때 추론 토큰은 출력으로 청구됩니다. 짧은 답변 뒤에도 많은 완료 토큰이 발생할 수 있으므로, 실제 프롬프트에서 노력 수준별 사용량을 비교하세요.
비용
정가는 다음과 같습니다.
- 입력 토큰 100만 개: 0.15달러
- 출력 토큰 100만 개: 0.50달러
- 캐시된 입력 토큰 100만 개: 0.03달러
2026년 9월 9일까지 50% 출시 할인이 적용되어 각각 0.075달러, 0.25달러, 0.015달러입니다.
OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra 등 리셀러의 가격은 별도로 적용됩니다. GLM-5.3-Flash 가격 분석에서 비용 계산과 할인 종료 후 변경 사항을 확인하고, 예산 산정 전 실제 사용하는 공급업체 가격을 검토하세요.
통합 테스트
멀티모달 페이로드와 모델 교체는 수동 검증이 번거롭습니다. base64 이미지 블록이 포함된 curl 요청은 작성·재실행이 불편하고, 모델 교체는 응답 형식을 조용히 바꿀 수 있습니다.
Apidog를 사용하면 텍스트·이미지·도구 호출을 컬렉션으로 저장하고, 애플리케이션이 읽는 응답 필드에 어설션을 추가할 수 있습니다. API 키도 셸에 직접 넣지 않고 환경 변수로 관리하세요.
출시 할인 종료 후 Flash를 유지할지 GLM-5.3으로 전환할지 검토할 때는 한 곳에서 모델 ID만 바꾸고 두 모델에 동일한 테스트 스위트를 실행하면 됩니다. 모델 마이그레이션을 추측이 아닌 검증 가능한 차이로 바꿀 수 있습니다.
자주 묻는 질문
정확한 모델 ID는 무엇인가요? Z.ai API에서는 glm-5.3-flash이고, OpenRouter에서는 z-ai/glm-5.3-flash입니다.
OpenAI SDK가 변경 없이 작동하나요? 채팅 완료, 스트리밍, 도구 호출에는 작동합니다. 다만 reasoning_effort 같은 비표준 매개변수는 Python SDK에서 extra_body가 필요합니다.
한 요청에 이미지를 몇 개 보낼 수 있나요? 각 이미지를 별도 image_url 블록으로 여러 개 보낼 수 있습니다. 실제 제한은 이미지 개수보다 컨텍스트 예산입니다.
응답이 너무 장황하고 느린 이유는 무엇인가요? reasoning_effort의 기본값이 max이기 때문입니다. 깊은 추론이 필요 없는 작업은 low로 설정하세요.
최대 출력 길이는 얼마인가요? 출처마다 다릅니다. OpenRouter는 131,072토큰, Hugging Face 카드는 163,840토큰을 제시합니다. 매우 긴 생성을 사용하기 전에는 공급업체 제한을 확인하세요.
Top comments (0)