close

DEV Community

Cover image for GLM-5.1 API 사용법: 코드 예제 완벽 가이드
Rihpig
Rihpig

Posted on • Originally published at apidog.com

GLM-5.1 API 사용법: 코드 예제 완벽 가이드

요약

GLM-5.1은 https://open.bigmodel.cn/api/paas/v4/의 BigModel API를 통해 사용할 수 있습니다. 이 API는 OpenAI와 완전히 호환되어, 동일한 엔드포인트 구조, 요청 형식, 스트리밍 패턴을 지원합니다. BigModel 계정, API 키, 그리고 모델 이름 glm-5.1만 준비하면 됩니다. 이 글에서는 인증 방법, 첫 요청, 스트리밍, 도구 호출, 그리고 Apidog를 활용한 통합 테스트까지 실전 위주로 다룹니다.

Apidog를 지금 사용해보세요

GLM-5.1 사용 예시

소개

GLM-5.1은 Z.AI의 주력 에이전트 모델입니다. 2026년 4월 출시 이후 SWE-Bench Pro에서 1위를 기록했으며, 주요 코딩 벤치마크를 모두 앞서고 있습니다. AI 코딩 도우미, 자율 에이전트, 장기 작업 실행 등 다양한 개발 시나리오에 바로 통합할 수 있습니다.

이미 GPT-4 또는 Claude 기반 코드를 보유하고 있다면, 기본 URL과 모델 이름만 변경하면 GLM-5.1로 손쉽게 전환할 수 있습니다. 추가 SDK 학습이나 응답 파싱 변경 없이 바로 적용 가능합니다.

💡 테스트는 에이전트 API 통합의 핵심입니다. 수백 개의 도구 호출을 포함하는 워크플로우를 실 API로 직접 테스트하면 할당량이 급격히 소모됩니다. Apidog의 테스트 시나리오 기능을 활용하면, 모든 응답 시퀀스를 모의(Mock)하여 실제 배포 전 스트리밍·도구호출·에러 시나리오를 완벽하게 검증할 수 있습니다. 아래의 테스트 섹션을 따라하려면 Apidog를 무료로 설치하세요.

사전 요구 사항

  1. bigmodel.cnBigModel 계정 (무료 가입)
  2. BigModel 콘솔의 API 키
  3. Python 3.8+ 또는 Node.js 18+ (예제 모두 지원)
  4. OpenAI SDK 또는 표준 requests/fetch 사용 (GLM-5.1 API는 OpenAI 호환)

API 키를 환경 변수로 저장:

export BIGMODEL_API_KEY="your_api_key_here"
Enter fullscreen mode Exit fullscreen mode

API 키는 코드에 하드코딩하지 마세요.

인증

모든 요청 헤더에 Bearer 토큰을 포함해야 합니다:

Authorization: Bearer YOUR_API_KEY
Enter fullscreen mode Exit fullscreen mode

BigModel API 키는 xxxxxxxx.xxxxxxxxxxxxxxxx처럼 점으로 구분된 2부 구조입니다. OpenAI의 sk- 형식과 다르지만 인증 방식은 동일합니다.

기본 URL

https://open.bigmodel.cn/api/paas/v4/
Enter fullscreen mode Exit fullscreen mode

채팅 완성 엔드포인트:

POST https://open.bigmodel.cn/api/paas/v4/chat/completions
Enter fullscreen mode Exit fullscreen mode

첫 번째 요청

curl 사용

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.1",
    "messages": [
      {
        "role": "user",
        "content": "Write a Python function that finds all prime numbers up to n using the Sieve of Eratosthenes."
      }
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'
Enter fullscreen mode Exit fullscreen mode

Python (requests) 사용

import os
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [
            {
                "role": "user",
                "content": "Write a Python function that finds all prime numbers up to n using the Sieve of Eratosthenes."
            }
        ],
        "max_tokens": 1024,
        "temperature": 0.7
    }
)

result = response.json()
print(result["choices"][0]["message"]["content"])
Enter fullscreen mode Exit fullscreen mode

OpenAI SDK 사용 (권장)

OpenAI와 완벽히 호환되므로 공식 OpenAI Python SDK를 바로 사용 가능합니다:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Write a Python function that finds all prime numbers up to n using the Sieve of Eratosthenes."
        }
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

OpenAI SDK는 재시도, 타임아웃, 응답 파싱까지 자동 처리합니다. 기본 URL만 BigModel로 지정하면 바로 적용됩니다.

응답 형식

OpenAI와 동일한 구조로 응답됩니다:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve_of_eratosthenes(n):\n    ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 215,
    "total_tokens": 247
  }
}
Enter fullscreen mode Exit fullscreen mode

응답 텍스트는 result["choices"][0]["message"]["content"]에서 가져올 수 있습니다.

usage 필드로 토큰 사용량을 추적하세요. GLM-5.1은 피크 시간(UTC+8 14:00-18:00)에 3배 할당량을 소모하므로, 토큰 사용량을 항상 체크해야 합니다.

스트리밍 응답

대용량 코드 생성 시, 스트리밍을 이용하면 토큰이 생성되는 즉시 받을 수 있습니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

stream = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Explain how a B-tree index works in a database, with a code example."
        }
    ],
    stream=True,
    max_tokens=2048
)

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

print()  # 스트리밍 종료 후 개행
Enter fullscreen mode Exit fullscreen mode

각 청크는 새로운 토큰의 델타만 포함합니다. 마지막 청크의 finish_reason이 "stop" (또는 토큰 제한 시 "length")입니다.

원시 요청으로 스트리밍

OpenAI SDK 없이 직접 요청할 수도 있습니다:

import os
import json
import requests

api_key = os.environ["BIGMODEL_API_KEY"]

response = requests.post(
    "https://open.bigmodel.cn/api/paas/v4/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "glm-5.1",
        "messages": [{"role": "user", "content": "Write a merge sort in Python."}],
        "stream": True,
        "max_tokens": 1024
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode("utf-8")
        if line.startswith("data: "):
            data = line[6:]
            if data == "[DONE]":
                break
            chunk = json.loads(data)
            delta = chunk["choices"][0]["delta"]
            if "content" in delta:
                print(delta["content"], end="", flush=True)
Enter fullscreen mode Exit fullscreen mode

도구 호출

GLM-5.1은 대화 중간에 함수 실행을 요청할 수 있는 도구 호출을 지원합니다. 에이전트 워크플로우(코드 실행, DB 조회, 외부 API 호출 등)에 핵심적으로 활용 가능합니다.

도구 정의

import os
import json
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BIGMODEL_API_KEY"],
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "run_python",
            "description": "Execute Python code and return the output. Use this to test, profile, or benchmark code.",
            "parameters": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string",
                        "description": "The Python code to execute"
                    }
                },
                "required": ["code"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read the contents of a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "File path to read"
                    }
                },
                "required": ["path"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="glm-5.1",
    messages=[
        {
            "role": "user",
            "content": "Write a function to compute Fibonacci numbers, test it for n=10, and show me the output."
        }
    ],
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message
print(f"Finish reason: {response.choices[0].finish_reason}")

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"\nTool called: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")
Enter fullscreen mode Exit fullscreen mode

도구 호출 응답 처리

도구 호출 발생 시, 실제 함수를 실행하고 결과를 모델에 반환하세요.

import subprocess

def execute_tool(tool_call):
    """도구 실행 후 결과 반환"""
    name = tool_call.function.name
    args = json.loads(tool_call.function.arguments)

    if name == "run_python":
        result = subprocess.run(
            ["python3", "-c", args["code"]],
            capture_output=True,
            text=True,
            timeout=10
        )
        return result.stdout or result.stderr

    elif name == "read_file":
        try:
            with open(args["path"]) as f:
                return f.read()
        except FileNotFoundError:
            return f"Error: file {args['path']} not found"

    return f"Unknown tool: {name}"


def run_agent_loop(user_message, tools, max_iterations=20):
    """도구 호출을 포함한 전체 에이전트 루프 실행"""
    messages = [{"role": "user", "content": user_message}]

    for i in range(max_iterations):
        response = client.chat.completions.create(
            model="glm-5.1",
            messages=messages,
            tools=tools,
            tool_choice="auto",
            max_tokens=4096
        )

        message = response.choices[0].message
        messages.append(message.model_dump())

        if response.choices[0].finish_reason == "stop":
            return message.content

        if response.choices[0].finish_reason == "tool_calls":
            for tool_call in message.tool_calls:
                tool_result = execute_tool(tool_call)
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": tool_result
                })

    return "Max iterations reached"


result = run_agent_loop(
    "Write a quicksort implementation, test it with a random list of 1000 integers, and report the time.",
    tools
)
print(result)
Enter fullscreen mode Exit fullscreen mode

이 패턴을 활용하면, 에이전트 모델의 도구 호출과 결과 처리를 완전 자동화할 수 있습니다.

주요 매개변수

매개변수 유형 기본값 설명
model string 필수 "glm-5.1" 사용
messages array 필수 대화 기록
max_tokens integer 1024 생성 최대 토큰 수 (최대 163,840)
temperature float 0.95 무작위성. 낮을수록 결정적
top_p float 0.7 핵심 샘플링. 코딩엔 0.7 추천
stream boolean false 스트리밍 응답 활성화
tools array null 도구 호출 함수 정의
tool_choice string/object "auto" "auto", "none", 특정 도구 지정
stop string/array null 사용자 정의 중지 시퀀스

코딩 작업 추천값:

{
    "model": "glm-5.1",
    "temperature": 1.0,
    "top_p": 0.95,
    "max_tokens": 163840  # 장기 실행·대용량 컨텍스트
}
Enter fullscreen mode Exit fullscreen mode

결정적 코드 출력을 원하면 temperature를 0.2~0.4로 낮추세요.

코딩 도우미와 함께 GLM-5.1 사용

Z.AI 코딩 플랜을 활용하면 BigModel API를 통해 Claude Code, Cline, Kilo Code 등 다양한 AI 코딩 도우미를 GLM-5.1로 라우팅할 수 있습니다. 저렴하게 강력한 코딩 모델을 활용할 수 있습니다.

Claude Code 설정

~/.claude/settings.json 등 설정 파일에 아래처럼 입력:

{
  "model": "glm-5.1",
  "baseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "apiKey": "your_bigmodel_api_key"
}
Enter fullscreen mode Exit fullscreen mode

Cline / Roo Code 설정

VS Code 또는 Cline 확장 설정:

{
  "cline.apiProvider": "openai",
  "cline.openAIBaseURL": "https://open.bigmodel.cn/api/paas/v4/",
  "cline.openAIApiKey": "your_bigmodel_api_key",
  "cline.openAIModelId": "glm-5.1"
}
Enter fullscreen mode Exit fullscreen mode

할당량 소비

GLM-5.1은 토큰당 과금이 아니라 Z.AI 할당량 시스템을 사용합니다:

  • 피크 시간 (UTC+8 14:00-18:00): 요청당 3배 할당량 소모
  • 비피크 시간: 요청당 2배 할당량 소모
  • 2026년 4월까지 프로모션: 비피크 시간 1배 할당량

대규모 에이전트 작업은 비피크 시간 예약이 효율적입니다.

Apidog로 GLM-5.1 API 테스트

에이전트 API 통합을 검증하려면, 일반 응답, 스트리밍, 도구 호출, 오류 등 다양한 상태를 모두 테스트해야 합니다. 실 API 호출은 할당량 소모 및 네트워크 연결이 필요합니다.

Apidog Smart Mock 예시

Apidog의 Smart Mock 기능을 활용하면, 실제 API 호출 없이 모든 응답 상태를 시뮬레이션할 수 있습니다.

Mock 엔드포인트 설정

  1. Apidog에서 새 엔드포인트 생성: POST https://open.bigmodel.cn/api/paas/v4/chat/completions
  2. 표준 성공 응답 Mock 등록:
{
  "id": "chatcmpl-test123",
  "object": "chat.completion",
  "created": 1744000000,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "def sieve(n): ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 120,
    "total_tokens": 152
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. 도구 호출 응답 Mock 등록:
{
  "id": "chatcmpl-tool456",
  "object": "chat.completion",
  "created": 1744000001,
  "model": "glm-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc",
            "type": "function",
            "function": {
              "name": "run_python",
              "arguments": "{\"code\": \"print(2+2)\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 35,
    "total_tokens": 83
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. 속도 제한(Mock 429) 응답 추가:
{
  "error": {
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
Enter fullscreen mode Exit fullscreen mode

전체 에이전트 루프 테스트

Apidog 테스트 시나리오로 여러 요청을 연결해 실제 에이전트 루프를 검증하세요.

  1. 1단계: 초기 메시지로 /chat/completions에 POST, HTTP 200 + finish_reason == "tool_calls" 검증
  2. 2단계: 도구 결과 포함 메시지로 다시 POST, HTTP 200 + finish_reason == "stop" 검증
  3. 3단계: 최종 응답 코드 추출 및 내용 검증

Mock 응답을 429로 바꿔 재시도 로직 등 에러 처리도 쉽게 검증할 수 있습니다.

여러 단계 워크플로우에서는 Apidog 변수 기능을 이용해 단계 간 값을 바로 전달할 수 있어, 실제 에이전트 루프와 동일하게 통합 테스트가 가능합니다.

오류 처리

API는 표준 HTTP 상태 코드를 반환합니다:

상태 의미 조치
200 성공 정상 처리
400 잘못된 요청 요청 형식 확인
401 인증 실패 API 키 확인
429 속도 제한 Retry-After 값만큼 대기 후 재시도
500 서버 오류 지수 백오프로 재시도
503 서비스 불가 지수 백오프로 재시도

실전 예시:

import time
import requests

def call_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://open.bigmodel.cn/api/paas/v4/chat/completions",
                headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}",
                         "Content-Type": "application/json"},
                json=payload,
                timeout=120
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            wait = 2 ** attempt
            print(f"Timeout on attempt {attempt + 1}. Retrying in {wait}s...")
            time.sleep(wait)

    raise Exception("Max retries exceeded")
Enter fullscreen mode Exit fullscreen mode

에이전트 실행이 길어질 수 있으니, 타임아웃을 넉넉히(120~300초) 설정하세요.

결론

GLM-5.1의 OpenAI 호환 API 덕분에 GPT 또는 Claude 기반 프로젝트는 몇 분 만에 GLM-5.1로 전환할 수 있습니다. 차이점은 엔드포인트(open.bigmodel.cn)와 할당량 기반 시스템뿐입니다.

수백 개 도구 호출이 포함된 장기 에이전트 앱 개발 시, GLM-5.1의 장기 최적화와 Apidog의 Smart Mock/테스트 시나리오로 엣지 케이스까지 확실히 검증하세요.

GLM-5.1의 상세 모델 비교는 GLM-5.1 모델 개요에서, Apidog로 에이전트 워크플로우 구축·테스트 방법은 AI 에이전트 메모리 작동 방식을 참고하세요.

자주 묻는 질문

GLM-5.1 API는 OpenAI와 호환됩니까?

네. 요청 형식, 응답 구조, 스트리밍, 도구 호출 모두 OpenAI 채팅 완성 API와 동일합니다. 기본 URL만 https://open.bigmodel.cn/api/paas/v4/로 지정하면 공식 OpenAI SDK 및 모든 호환 클라이언트에서 사용 가능합니다.

API 요청에 사용할 모델 이름은?

모델 이름은 "glm-5.1"입니다. 전체 버전명이 아닌 "glm-5.1"만 사용하세요.

GLM-5.1 API 요금 체계는?

BigModel API는 할당량 기반입니다. GLM-5.1은 피크 시간(UTC+8 14:00-18:00) 3배, 비피크 2배 할당량. 2026년 4월까지 비피크 시간은 1배 프로모션 적용.

최대 컨텍스트 길이 및 출력 토큰 제한?

입력 컨텍스트 최대 200,000 토큰, 출력 최대 163,840 토큰. 긴 작업은 max_tokens를 32,768 이상 권장.

함수 호출/도구 사용 가능한가?

네. OpenAI와 동일하게 type: "function" 스키마로 도구 정의, tools 배열 전달, finish_reason: "tool_calls" 처리 방식입니다.

할당량 소모 없이 API 테스트하려면?

Apidog의 Smart Mock으로 성공, 도구 호출, 속도 제한, 오류 등 모든 상태를 모의 응답으로 정의하세요. 개발·테스트는 Mock으로, 실제 API는 배포 전 최종 검증에만 사용하세요.

GLM-5.1 모델 가중치는 어디서?

오픈소스 가중치는 HuggingFace의 zai-org/GLM-5.1에서 MIT 라이선스로 제공되며, vLLM, SGLang 등 로컬 추론 지원.

Top comments (0)