GLM-5.2 API 사용법

GLM-5.2 API는 Z.ai의 최신 오픈 가중치 플래그십 모델에 대한 프로그래밍 방식의 접근을 제공합니다. 이 모델은 장기 코딩 벤치마크에서 오픈소스 모델 중 가장 높은 점수를 받은 약 753B 매개변수 MoE 모델입니다. 이 가이드는 실습 위주로 구성되어 있습니다. API 키를 받고 첫 요청을 전송한 다음 Python, curl, 사고 모드, 스트리밍, 도구 호출 및 비용 추적을 실제 값을 터미널에 붙여넣어 가며 진행합니다.

이전 릴리스에서 오신 분들은 여기부터 시작하세요.

버튼

GLM-5.1 이후 변경된 사항

GLM-5.2는 5.1 세대를 대체합니다. GLM-5.1 API에 대해 통합 코드를 이미 작성했다면, 와이어 포맷은 동일하므로 대부분 모델 ID만 바꾸면 됩니다. 알아두어야 할 차이점은 다음과 같습니다.

새로운 스파스 어텐션 방식. GLM-5.2는 “IndexShare”를 도입하여 4개의 스파스 어텐션 레이어마다 하나의 인덱서를 재사용함으로써 긴 컨텍스트에서 어텐션 비용을 절감합니다. API 사용자로서 이를 직접 건드릴 필요는 없으며, 1M 토큰 창을 더 저렴하게 제공할 수 있게 합니다.
에이전트 코딩의 실질적인 도약. Z.ai가 발표한 결과에 따르면 Terminal-Bench 2.1은 GLM-5.1의 62.0에서 81.0으로 상승했습니다. 이는 코딩 에이전트를 구축하는 모든 사람들에게 중요한 통계입니다.
두 가지 사고 노력 수준. GLM-5.2는 높은(High) 및 최대(Max) 추론 노력을 제공하며, Z.ai는 코딩 작업에 최대(Max)를 권장합니다. 이에 대한 자세한 내용은 아래에서 설명합니다.

5.1 요청 코드가 이미 작동하므로 이 가이드에서는 다시 다루지 않습니다. 여기의 모든 내용은 glm-5.2를 직접 대상으로 합니다.

1단계: GLM-5.2 API 키 받기

z.ai에 로그인하여 계정 대시보드의 API 키 섹션을 엽니다. 키를 생성하고 한 번 복사(보통 다시 볼 수 없음)한 후 소스 코드에 붙여넣는 대신 환경 변수에 저장합니다:

export ZAI_API_KEY="your-glm-5.2-api-key"

glm-5.2 API 키를 Git에서 제외하십시오. 유출된 키는 귀하의 계정으로 청구되며, GLM-5.2 출력은 백만 토큰당 가격이 책정되므로 폭주하는 스크립트는 실제 비용을 발생시킵니다.

2단계: 엔드포인트와 base_url 알아보기

GLM-5.2는 OpenAI Chat Completions 형식과 호환되므로, 기본 URL을 변경하면 OpenAI Chat Completions 형식을 사용하는 모든 클라이언트가 작동합니다. 필요한 값은 다음과 같습니다:

설정	값
채팅 완료 엔드포인트	`https://api.z.ai/api/paas/v4/chat/completions`
기본 URL (SDK용)	`https://api.z.ai/api/paas/v4/`
모델 ID	`glm-5.2`
인증	`Authorization: Bearer $ZAI_API_KEY`

Z.ai를 직접 호출하는 대신 OpenRouter를 통해 라우팅하는 것을 선호하는 경우 OpenRouter 별칭은 z-ai/glm-5.2입니다. 로컬 실행의 경우 Ollama는 가중치를 glm-5.2로 게시하며(Ollama 라이브러리 참조), 오픈 가중치는 MIT 라이선스 하에 Hugging Face에 있습니다.

구축 전에 제한 사항에 대한 참고: 컨텍스트 창은 1M 토큰(1,048,576)입니다. 최대 출력의 경우 z.ai 문서에는 최대 128K로 나와 있지만, OpenRouter는 숫자를 게시하지 않으므로 고정된 보장이라기보다는 z.ai 문서에 따라 최대 128K로 간주하십시오 (실시간 확인 필요).

3단계: curl로 첫 요청 보내기

다음은 최소한의 GLM-5.2 curl 호출입니다. 하나의 사용자 메시지를 보내고 JSON 응답을 출력합니다:

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.2",
    "messages": [
      {"role": "system", "content": "당신은 간결한 백엔드 엔지니어입니다."},
      {"role": "user", "content": "고객별 최신 주문 5개를 반환하는 SQL 쿼리를 작성하세요."}
    ]
  }'

응답 형식은 OpenAI 표준과 일치합니다: id, 어시스턴트 메시지가 포함된 choices 배열, 그리고 usage 객체. 마지막 필드는 비용을 추적하는 방법이며, 이 가이드의 마지막 부분에서 다룹니다.

4단계: OpenAI SDK를 사용하여 Python에서 호출하기

API가 OpenAI와 호환되므로 특별한 클라이언트가 필요하지 않습니다. 표준 SDK를 설치하고 base_url을 Z.ai로 지정하십시오. 다음은 GLM-5.2의 표준 Python 설정입니다:

pip install openai

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ZAI_API_KEY"],
    base_url="https://api.z.ai/api/paas/v4/",
)

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {"role": "system", "content": "당신은 간결한 백엔드 엔지니어입니다."},
        {"role": "user", "content": "멱등성 키(idempotency keys)를 3문장으로 설명하세요."},
    ],
)

print(resp.choices[0].message.content)

이것이 전체 통합입니다. client 객체는 OpenAI에 대해 작동하는 방식과 정확히 동일하게 작동하므로 기존 도우미 코드, 재시도 및 로깅이 모두 이어집니다. 플랫폼 자체에 대한 더 심층적인 투어를 원하시면, GLM-5 API 개요에서 전체 제품군의 규칙을 다룹니다.

5단계: 사고(thinking) 및 추론 노력(reasoning_effort)으로 추론 제어하기

GLM-5.2는 추론 모델입니다. 내부 사고를 켜거나 끌 수 있으며, 켰을 때 얼마나 열심히 작동할지 설정할 수 있습니다.

빠르고 저렴하며 지연 시간이 짧은 응답(분류, 짧은 다시 쓰기, 라우팅)의 경우 사고를 비활성화합니다:

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "분류: '내 카드가 두 번 청구되었습니다'"}],
    extra_body={"thinking": {"type": "disabled"}},
)

어려운 코딩 및 수학 작업의 경우 사고를 활성화하고 노력을 최대로 설정하십시오. Z.ai는 특히 코딩에 최대(Max)를 권장합니다:

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {"role": "user", "content": "이 함수를 N+1 쿼리를 제거하도록 리팩토링하고 수정 사항을 설명하세요."},
    ],
    extra_body={
        "thinking": {"type": "enabled"},
        "reasoning_effort": "max",
    },
)

extra_body 래퍼는 OpenAI Python SDK가 비표준 필드를 Z.ai로 전달하는 방식입니다. 원시 curl 본문에서는 thinking과 reasoning_effort를 model 옆의 최상위 수준에 배치합니다. 최대 노력은 더 많은 출력 토큰(추론 카운트)을 소모하므로, 품질 향상이 그만한 가치가 있는 작업에만 사용하십시오.

6단계: 응답 스트리밍하기

채팅 UI 및 긴 생성의 경우, 전체 완료를 기다리는 대신 토큰이 도착하는 대로 스트리밍합니다. stream: true로 설정하고 청크를 반복합니다:

stream = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "속도 제한 수정에 대한 200단어 분량의 변경 로그 항목을 작성하세요."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

curl에서는 본문에 "stream": true를 추가하면 서버는 Server-Sent Events를 반환하며, 각 청크당 하나의 data: 줄이 있고 data: [DONE]으로 끝납니다. 스트리밍은 가격 책정에 아무런 영향을 주지 않습니다. 여전히 토큰당 요금을 지불하지만, 더 빨리 볼 수 있을 뿐입니다.

7단계: 함수 및 도구 호출

도구 호출은 GLM-5.2의 에이전트 역량이 드러나는 부분으로, Z.ai가 발표한 결과에서 MCP-Atlas 77.0점을 기록하여 Claude Opus 4.8과 거의 비슷한 수준입니다. 패턴은 표준 OpenAI 2단계 방식입니다: 도구를 설명하고, 모델이 tool_calls 요청을 반환하면, 함수를 실행한 다음 결과를 다시 모델에 피드백합니다.

다음은 날씨 조회 기능을 사용한 작고 현실적인 GLM-5.2 API 예제입니다:

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "도시의 현재 온도를 가져옵니다.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "도시 이름, 예: Berlin"},
                    "unit": {"type": "string", "enum": ["c", "f"]},
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "베를린의 날씨는 섭씨로 어떻게 되나요?"}]

first = client.chat.completions.create(
    model="glm-5.2",
    messages=messages,
    tools=tools,
)

call = first.choices[0].message.tool_calls[0]
args = json.loads(call.function.arguments)

# 여기에서 실제 함수를 실행합니다. 예제를 위해 스텁 처리되었습니다:
def get_weather(city, unit="c"):
    return {"city": city, "temp": 12, "unit": unit}

result = get_weather(**args)

# 어시스턴트의 도구 호출, 그리고 도구의 결과를 추가합니다.
messages.append(first.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": call.id,
    "content": json.dumps(result),
})

final = client.chat.completions.create(
    model="glm-5.2",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)

모델은 도구를 호출할 시기를 결정하고, 사용자가 이를 실행하면, 두 번째 요청을 통해 GLM-5.2는 원시 결과를 자연스러운 답변으로 바꿀 수 있습니다. 동일한 루프는 여러 도구 및 에이전트 프레임워크로 확장될 수 있으며, 계약상의 어떠한 내용도 Z.ai에 국한되지 않습니다.

이 루프를 수동으로 테스트하는 것은 금방 지루해집니다. 이럴 때 Apidog를 사용하는 것이 좋습니다. GLM-5.2 엔드포인트를 한 번 정의하고, 각 사고 모드에 대한 요청 본문을 저장하며, 매번 curl을 다시 작성할 필요 없이 도구 호출을 다시 재생할 수 있습니다. Apidog는 OpenAI 스타일 스키마를 처리하고 스트리밍 응답을 한 곳에서 검사할 수 있도록 합니다.

8단계: 비용 추적을 위해 사용량(usage) 객체 읽기

스트리밍되지 않는 모든 응답에는 usage 객체가 포함됩니다. 이것이 청구에 대한 신뢰할 수 있는 정보원입니다:

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "REST와 gRPC를 4가지 요점으로 요약하세요."}],
)

u = resp.usage
print(u.prompt_tokens, u.completion_tokens, u.total_tokens)

GLM-5.2 가격은 100만 입력 토큰당 $1.40, 100만 출력 토큰당 $4.40입니다 (OpenRouter 확인). 캐시된 입력은 100만당 약 $0.26입니다 (VentureBeat의 수치 인용). 따라서 8,000개의 입력 토큰과 1,500개의 출력 토큰을 사용하는 호출의 대략적인 비용은 다음과 같습니다:

(8000 / 1_000_000 * 1.40) + (1500 / 1_000_000 * 4.40)
= 0.0112 + 0.0066
= 약 $0.0178

최대 노력으로 인한 추론 토큰은 출력 개수에 포함되므로, 최대 노력 코딩 호출은 사고 비활성화 호출보다 더 비쌀 것입니다. VentureBeat는 GLM-5.2가 “장기 코딩에서 GPT-5.5를 약 1/6의 비용으로 능가한다”고 보고하며, 이는 이러한 수치 뒤에 있는 경제적 주장입니다 (VentureBeat에 주장을 귀속).

API 호출당 요금제 대신 정액 요금제를 선호하는 경우, Z.ai는 GLM 코딩 플랜 계층(Lite, Pro, Max, Team)도 판매합니다. 정확한 가격은 변동되므로, 2026년 6월 현재 최신 계층을 z.ai에서 확인한 후 결정하십시오. 종량제 측면에서 직접 비교를 원하시면 GLM-5.2 가격 분석에서 더 자세한 내용을 다루고 있으며, GLM-5.2를 무료로 사용하는 방법은 로컬 가중치 경로를 다룹니다.

Claude Code 내에서 GLM-5.2 사용하기

GLM-5.2는 Anthropic 호환 경로도 제공하므로 Claude Code에서 이를 구동할 수 있습니다. 코딩 기본 URL을 https://api.z.ai/api/coding/paas/v4로 지정한 다음(일부 소스에서는 open.z.ai/api/paas/v4로 표시되므로 실시간 확인 필요), 다음 환경 변수를 설정합니다:

export ANTHROPIC_BASE_URL="https://api.z.ai/api/coding/paas/v4"
export ANTHROPIC_API_KEY="your-glm-coding-plan-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5.2[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5.2[1m]"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000
export API_TIMEOUT_MS=3000000

[1m] 접미사는 1M 컨텍스트 변형을 선택하며, 긴 API_TIMEOUT_MS가 중요합니다. 이것이 없으면 Claude Code는 긴 대규모 컨텍스트 호출이 반환되기 전에 종료시킬 수 있습니다. 전체 안내서는 Claude Code와 함께 GLM 실행하기 가이드에 있으며, 도구를 비교하고 있다면 Claude Code vs Codex vs Cursor vs GLM Plan에서 장단점을 설명합니다.

GLM-5.2는 어떤가요?

통합 결정을 내리는 데 필요한 값에 대한 빠른 참조:

속성	GLM-5.2
모델 ID (API)	`glm-5.2`
아키텍처	약 753B MoE, BF16, IndexShare 스파스 어텐션
컨텍스트 창	1M 토큰 (1,048,576)
최대 출력	z.ai 문서에 따라 최대 128K (실시간 확인 필요)
사고 모드	높음(High) / 최대(Max), 또는 비활성화됨(disabled)
입력 가격	$1.40 / 1M 토큰
출력 가격	$4.40 / 1M 토큰
라이선스	MIT, 오픈 가중치

벤치마크 세부 정보의 경우, Z.ai가 발표한 결과에는 SWE-bench Pro 62.1 (GPT-5.5 58.6), 도구를 사용한 Humanity’s Last Exam 54.7, AIME 2026 99.2가 포함됩니다. GLM-5.2 벤치마크 종합은 이를 분석하며, GLM-5.2 vs GPT-5.5, Claude Opus, Gemini는 이들을 나란히 비교합니다.

자주 묻는 질문 (FAQ)

GLM-5.2 API는 정말 OpenAI와 호환됩니까? 예. OpenAI SDK의 base_url을 https://api.z.ai/api/paas/v4/로 지정하고 모델을 glm-5.2로 설정하십시오. 표준 채팅, 스트리밍, 도구 호출 코드는 변경 없이 작동합니다.

어떤 GLM-5.2 모델 ID를 보내야 합니까? Z.ai API에 glm-5.2를 보내십시오. OpenRouter에서는 z-ai/glm-5.2이고, Ollama에서는 glm-5.2이며, Claude Code 변형은 1M 컨텍스트 창에 대해 glm-5.2[1m]입니다.

속도를 위해 추론을 끄려면 어떻게 합니까? thinking: {"type": "disabled"}를 전달합니다 (Python SDK의 extra_body를 통해). 어려운 코딩 작업의 경우, 사고를 활성화하고 reasoning_effort: "max"로 설정하십시오. 이는 Z.ai가 코드에 권장하는 설정입니다.

GLM-5.2는 호출당 비용이 얼마입니까? 100만 입력 토큰당 $1.40, 100만 출력 토큰당 $4.40입니다 (OpenRouter 확인). 각 응답의 usage 객체를 읽어 정확한 비용을 계산하십시오. 최대 노력 추론 토큰은 출력으로 계산됨을 기억하십시오.

GLM-5.2에 비전 모델이 있습니까? 2026년 6월 현재 확인된 비전 변형은 없습니다. API는 텍스트 입력, 텍스트 출력입니다. Z.ai가 지원을 문서화하기 전까지는 이미지 입력에 의존하지 마십시오.

마무리

GLM-5.2 API는 OpenAI 호환 코드베이스에서 쉽게 전환할 수 있습니다. 기본 URL을 바꾸고 glm-5.2를 보내면 1M 컨텍스트를 가진 MIT 라이선스 코딩 모델을 사용할 수 있으며, 100만 토큰당 $4.40의 출력 가격으로 조절 가능한 추론 기능을 제공합니다. curl 핑으로 시작하여 Python SDK로 이동한 다음, 사용 사례에 따라 사고 모드와 도구 호출을 추가하십시오.

엔드포인트를 테스트하고, 요청 변형을 저장하고, 매번 curl을 수동으로 작성하지 않고도 도구 호출 단계를 검사할 준비가 되면, Apidog를 다운로드하여 GLM-5.2 엔드포인트를 한 번 설정하십시오. 모델 자체에 대한 더 큰 그림을 보려면 GLM-5.2란 무엇인가 및 GLM-5.2 vs GLM-5.1 비교를 참조하십시오.

버튼