Z.AI API 사용법: GLM 가격·무료 모델과 첫 호출, 오류 해결

Z.AI(GLM) API는 일반 API 키와 잔액을 준비한 뒤, OpenAI SDK의 주소를 https://api.z.ai/api/paas/v4/로 바꿔 호출한다. 무료로 쓰려면 GLM-4.7-Flash나 GLM-4.5-Flash를 고른다. 코딩 도구용 Coding Plan은 키·과금·주소가 다른 별도 상품이다.

요금과 무료 모델

GLM-4.7-Flash와 GLM-4.5-Flash는 입력·출력 모두 무료다. 최신 GLM-5.3 계열은 유료이며 100만 토큰당 가격은 다음과 같다. 9월 26일 Z.AI 가격표 기준이다.

모델	입력	캐시 입력	출력
GLM-5.3	$1.4	$0.26	$4.4
GLM-5.3-FlashX	$0.37	$0.075	$1.25
GLM-5.3-Flash	$0.15	$0.03	$0.50
GLM-4.7-Flash	무료	무료	무료
GLM-4.5-Flash	무료	무료	무료

캐시 입력 보관료는 지금 기간 한정 무료다. 이미지 입력이 필요하면 무료 비전 모델 GLM-4.6V-Flash가 있다. 웹 검색 도구는 1회 $0.01이 따로 붙는다.

입력 1만·출력 1천 토큰짜리 요청 1,000건으로 계산하면 차이가 분명하다. 입력 1,000만 토큰과 출력 100만 토큰이다.

모델	계산	1,000건 비용
GLM-5.3	10 × $1.4 + 1 × $4.4	$18.40
GLM-5.3-FlashX	10 × $0.37 + 1 × $1.25	$4.95
GLM-5.3-Flash	10 × $0.15 + 1 × $0.50	$2.00
GLM-4.7-Flash	무료	$0

GLM-5.3은 thinking이 항상 켜져 있어 출력 토큰이 예상보다 늘 수 있다. 분류·요약처럼 단순한 일은 Flash 계열로 먼저 시험한다.

1. 일반 API 키와 Python 환경 준비

Z.AI API Keys에서 일반 API 키를 만들고, 콘솔의 Billing에서 잔액을 확인한다. (Quick Start) PowerShell에서 python --version이 3.10 이상인지 본 뒤 아래를 실행한다. 3.10은 현재 OpenAI Python SDK의 최소 조건이다.

New-Item -ItemType Directory -Force "$env:USERPROFILE\glm-api-test" | Out-Null
Set-Location "$env:USERPROFILE\glm-api-test"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade openai
$env:ZAI_API_KEY="발급한_일반_API_키"
notepad glm_first.py

키 환경 변수는 창을 닫으면 사라지니 새 창에서는 다시 넣는다. 키는 Python 파일에 적지 않는다.

2. 파일을 저장하고 첫 응답 받기

메모장에 아래 코드를 붙여 넣고 UTF-8로 저장한다. 파일 형식을 모든 파일로 골라 glm_first.py.txt가 되지 않게 한다.

import os
from openai import OpenAI

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",
    messages=[{
        "role": "user",
        "content": "가격 1200원인 물건 3개의 합계를 계산해 숫자와 원 단위만 답해줘.",
    }],
    reasoning_effort="low",
    extra_body={"thinking": {"type": "enabled"}},
)

print("모델:", response.model)
print("답:", response.choices[0].message.content)
print("종료 사유:", response.choices[0].finish_reason)
print("사용량:", response.usage.model_dump() if response.usage else None)

.\.venv\Scripts\python.exe .\glm_first.py

답이 3,600원이고, 빈 문자열이 아니며, 사용량:에 토큰 정보가 나오면 성공이다. 3,600원과 3600원처럼 쉼표만 다른 답은 정상이다. 콘솔 사용량에도 요청이 잡혔는지 본다.

GLM-5.3 설정표에 따르면 thinking은 끌 수 없고 reasoning_effort는 low·high·max를 지원한다. 생략하면 max라 비용이 커지니 첫 연결은 low로 명시한다. thinking은 OpenAI SDK 표준 필드가 아니어서 extra_body로 보낸다.

무료 모델로 바꾸려면 model 값을 glm-4.7-flash로 바꾼다. 위 두 설정은 GLM-5.3 기준이니, 무료 모델에서 파라미터 오류가 나면 reasoning_effort와 extra_body 줄을 빼고 다시 실행한다.

3. 오류 해결

Z.AI는 HTTP 상태와 본문의 상세 코드를 함께 쓴다. 429만 보고 기다리지 말고 안쪽 error.code를 읽는다. (API 오류 코드)

보이는 오류	조치
KeyError: ZAI_API_KEY	같은 PowerShell 창에서 환경 변수를 넣고 실행
No module named openai	.venv의 Python으로 설치와 실행을 통일
HTTP 401, 코드 1000·1001·1003	키 누락·인증 실패·만료. 노출됐거나 만료됐으면 재발급
HTTP 400, 코드 1210	파라미터 오류. GLM-5.3에 thinking.type: "disabled"를 보내지 않는다
HTTP 400, 코드 1211	모델 ID 오탈자. 예제의 glm-5.3과 대조
HTTP 400, 코드 1261 Prompt too long	입력이 컨텍스트를 넘었다. 자료를 나누거나 대화를 새로 시작
HTTP 429, 코드 1113	일반 API 잔액 부족. Coding Plan 포인트로는 채워지지 않는다
HTTP 429, 코드 1302·1305	요청 과다·일시 과부하. 반복 호출을 멈추고 나중에 재시도

키가 틀리면 실제로 이렇게 나온다. Techies Note가 9월 25일 일부러 틀린 키로 https://api.z.ai/api/paas/v4/chat/completions에 요청하니 HTTP 401과 다음 본문이 돌아왔다. 문서 표의 1000번대 코드가 아니라 code에 "401"이 들어 있었다. 키 앞뒤에 공백이나 따옴표가 붙지 않았는지 먼저 본다.

{"error":{"code":"401","message":"token expired or incorrect"}}

기존 코드를 옮길 때는 이 예제가 동작한 뒤 GLM-5.3의 추론 설정 변화를 적용한다.

일반 API와 Coding Plan을 섞지 않는다

사용할 곳	Base URL	상품
자체 Python 앱(이 글)	https://api.z.ai/api/paas/v4/	일반 API
지원 코딩 도구의 Chat Completions	https://api.z.ai/api/coding/paas/v4	Coding Plan
Responses 방식을 쓰는 지원 코딩 도구	https://api.z.ai/api/v1	Coding Plan
Claude Code(Anthropic 호환)	https://api.z.ai/api/anthropic	Coding Plan

Coding Plan은 공식 지원 도구 안에서만 쓰는 상품이라 자체 앱에는 일반 API 주소를 쓴다. Codex처럼 Responses를 요구하는 도구는 Codex 연결 안내를 따른다. Claude Code에 구독을 연결하려면 GLM Coding Plan 설정 가이드를 본다. (Coding Plan 이용 정책)

자주 묻는 질문

Coding Plan 구독이 있으면 이 코드도 공짜인가? 아니다. 자체 앱의 호출은 일반 API 잔액에서 빠진다. 일반 잔액이 없으면 429와 코드 1113이 난다.

GLM-5.3과 Flash 중 무엇을 쓰나? 여러 단계를 거치는 코딩·분석은 GLM-5.3, 짧은 분류·요약·번역은 GLM-5.3-Flash나 무료 GLM-4.7-Flash가 맞다. 같은 입력으로 두 모델의 답과 사용량을 비교해 고른다.