Z.AI API 사용법 (GLM-4.7) — CURL 완전 가이드

핵심 인사이트 (3줄 요약)

Z.AI는 GLM-4.7 모델을 Anthropic Messages API 포맷으로 제공하는 서비스다. 기존 Anthropic/Claude API와 동일한 스펙으로, 헤더와 엔드포인트만 바꾸면 바로 사용 가능하다. CURL 한 줄로 요청하며, 스트리밍 · 멀티턴 대화 · 커스텀 시스템 프롬프트를 모두 지원한다.

1. 개념

2. 설정

환경 변수

# API Key (Z.AI 콘솔에서 발급)
export ZAI_API_KEY="your_api_key_here"

# API 엔드포인트
export ZAI_BASE_URL="https://api.z.ai/api/anthropic/v1/messages"

# 모델
export ZAI_MODEL="glm-4.7"

3. CURL 사용법

3.1 기본 요청

curl -s "$ZAI_BASE_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -d '{
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "안녕하세요"}],
    "max_tokens": 1024
  }'

3.2 시스템 프롬프트 포함

curl -s "$ZAI_BASE_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -d '{
    "model": "glm-4.7",
    "system": "당신은 유능한 기술 문서 작성자입니다.",
    "messages": [{"role": "user", "content": "Rust의 소유권 개념을 설명해줘"}],
    "max_tokens": 2048
  }'

3.3 멀티턴 대화

curl -s "$ZAI_BASE_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -d '{
    "model": "glm-4.7",
    "messages": [
      {"role": "user",      "content": "Rust란 무엇인가요?"},
      {"role": "assistant", "content": "Rust는 시스템 프로그래밍 언어로..."},
      {"role": "user",      "content": "소유권 개념을 더 자세히 설명해줘"}
    ],
    "max_tokens": 2048
  }'

3.4 스트리밍 응답

curl -s "$ZAI_BASE_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -d '{
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "긴 글을 써줘"}],
    "max_tokens": 4096,
    "stream": true
  }'

4. 테스트 스크립트 (test_zai_api.sh)

#!/bin/bash
# test_zai_api.sh

# Configuration
ZAI_API_KEY="YOUR_API_KEY"
ZAI_BASE_URL="https://api.z.ai/api/anthropic/v1/messages"
ZAI_MODEL="glm-4.7"

echo "=== Z.AI API 연결 테스트 ==="

RESPONSE=$(curl -s "$ZAI_BASE_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -d "{
    \"model\": \"$ZAI_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"안녕하세요\"}],
    \"max_tokens\": 256
  }")

echo "$RESPONSE" | python3 -m json.tool 2>/dev/null || echo "$RESPONSE"

실행:

chmod +x test_zai_api.sh
./test_zai_api.sh

5. 응답 예시

{
  "id": "msg_2026020109373013301dbd71d34b21",
  "type": "message",
  "role": "assistant",
  "model": "glm-4.7",
  "content": [
    {
      "type": "text",
      "text": "안녕하세요! 반갑습니다. 😊\n\n저는 Z.ai의 GLM-4.7 모델입니다..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 9,
    "output_tokens": 30,
    "cache_read_input_tokens": 0
  }
}

응답에서 텍스트만 추출:

echo "$RESPONSE" | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(data['content'][0]['text'])
"

6. API 레퍼런스

헤더

요청 파라미터

messages 배열 구조

[
  {"role": "user",      "content": "질문"},
  {"role": "assistant", "content": "답변"},
  {"role": "user",      "content": "후속 질문"}
]

7. 지원 모델

8. Python으로 사용하기

import requests
import os

url = "https://api.z.ai/api/anthropic/v1/messages"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['ZAI_API_KEY']}"
}
payload = {
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "안녕하세요"}],
    "max_tokens": 1024
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data["content"][0]["text"])

9. Anthropic SDK 호환 사용

Z.AI는 Anthropic API 포맷을 그대로 사용하므로, Anthropic 공식 SDK에서 base_url만 바꿔도 작동한다.

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_ZAI_API_KEY",
    base_url="https://api.z.ai/api/anthropic"
)

message = client.messages.create(
    model="glm-4.7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "안녕하세요"}]
)
print(message.content[0].text)

10. 주의사항

참고

• Z.AI 공식 문서
• API Key 발급
• Anthropic Messages API 스펙