GLM-5.3-Flash는 OpenAI와 호환됩니다. 즉, 기존 클라이언트의 기본 URL을 다른 주소로 변경하고 문자열 하나만 바꾸면 가장 빠르게 작동하는 호출 경로를 확보할 수 있습니다. 정말 새로운 부분은 이미지 입력입니다. 이 모델은 텍스트와 같은 요청에서 그림을 받는 첫 번째 GLM-5 모델이며, 페이로드 형태가 사용자들을 혼란스럽게 할 수 있습니다.
이 가이드에서는 키 발급, 텍스트 호출, 이미지 전송, 추론 노력 제어, 스트리밍 및 도구 호출에 대해 다룹니다. 모든 예시에서는 모델 ID glm-5.3-flash를 사용합니다.
이 모델을 연결하기 전에 어떤 모델인지 배경 지식이 필요하다면, 저희 GLM-5.3-Flash 설명서를 먼저 확인하세요. 만약 더 큰 자매 모델을 이미 사용하고 있다면, GLM-5.3 API 가이드에서 해당 모델을 다루고 있으며, 아래의 차이점들은 실제입니다: 다른 모델 ID, 다른 요금표, 그리고 GLM-5.3이 기본적으로 가지고 있지 않은 이미지 경로입니다.
API 키 발급받기
z.ai에서 계정을 생성하고, 대시보드의 API 키 섹션을 열어 키를 생성하세요. 소스 코드 대신 환경 변수에 저장하는 것이 좋습니다:
export ZAI_API_KEY="your-key-here"
표준 API의 기본 URL은 다음과 같습니다:
https://api.z.ai/api/paas/v4/
코딩-플랜 엔드포인트에서 사용하는 별도의 기본 URL이 있으며, API를 직접 호출하는 대신 Claude Code 또는 Cline을 연결하는 경우 중요합니다. 해당 설정은 저희 Claude Code 및 Cline 가이드에 설명되어 있습니다.
첫 번째 호출
엔드포인트가 OpenAI와 호환되므로 공식 OpenAI SDK는 수정 없이 작동합니다:
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["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 "Authorization: Bearer $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에서는 다음과 같습니다:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.ZAI_API_KEY,
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과 모델 문자열을 제외하고는 GLM에만 해당되는 내용은 없습니다. 이것이 OpenAI 호환 인터페이스의 요점이며, 자체 작업 부하에 대해 실제로 벤치마킹할 가치가 있을 만큼 모델 교체가 저렴한 이유입니다.
이미지 전송하기
이 섹션은 GLM-5.3에는 없는 내용입니다. 이미지 입력은 콘텐츠 블록을 통해 작동합니다. 즉, 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 비전 가이드를 참조하세요.
추론 노력 제어하기
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로 설정하면 출력 토큰 수를 상당히 줄일 수 있습니다.
이것은 High와 Max만 노출했던 GLM-5.2와의 변경 사항입니다. low 티어는 새로운 기능이며, 비용에 민감한 배치 작업의 경우 모델에서 가장 유용한 매개변수일 것입니다.
reasoning_effort는 표준 OpenAI 스키마의 일부가 아니므로 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초로 양호하므로, 응답은 빠르게 시작하여 빠르게 도착하기보다는 꾸준히 도착합니다. 사용자 인터페이스로 스트리밍하는 경우 이 프로필은 괜찮습니다. 배치 작업에서 긴 문서를 생성하는 경우 이에 대한 예산을 책정해야 합니다.
도구 호출
도구는 표준 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 기본값으로 설정된 경우, 추론 토큰은 출력으로 청구되므로 짧은 가시적 답변 뒤에 많은 완료 토큰 수가 숨어 있을 수 있습니다. 자체 프롬프트에서 노력 수준별로 이 숫자를 비교하는 것이 어떤 설정이 실제로 필요한지 결정하는 가장 빠른 방법입니다.
비용
정가 책정은 백만 입력 토큰당 0.15달러, 백만 출력 토큰당 0.50달러, 백만 캐시된 입력 토큰당 0.03달러입니다. 2026년 9월 9일까지 50% 출시 할인이 적용되어 이 가격은 각각 0.075달러, 0.25달러, 0.015달러로 절반이 됩니다.
가격은 리셀러마다 다릅니다. OpenRouter, Cloudflare Workers AI, Vercel AI Gateway, DeepInfra 등은 모두 자체 요율로 모델을 제공합니다. 저희 가격 분석은 비용 계산과 할인이 만료될 때 변경되는 사항을 설명합니다. 예산을 책정하기 전에 실제로 사용하는 공급업체의 수치를 확인하세요.
통합 테스트
이 API의 두 가지 사항은 수동으로 확인하기가 번거롭습니다. 멀티모달 페이로드가 장황하므로 curl 명령에서 base64 이미지 블록을 작성하는 것은 번거롭고 다시 실행하는 것은 더 나쁩니다. 또한 모델 교체는 응답 형태를 소리 없이 변경하는 종류의 변경입니다.
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토큰을 나열합니다. 매우 긴 생성을 의존하기 전에 공급업체에 확인하세요.