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

요약

GLM-5.1은 https://open.bigmodel.cn/api/paas/v4/의 BigModel API를 통해 사용할 수 있습니다. 이 API는 OpenAI와 호환됩니다: 동일한 엔드포인트 구조, 동일한 요청 형식, 동일한 스트리밍 패턴을 가집니다. BigModel 계정, API 키, 그리고 모델 이름 glm-5.1이 필요합니다. 이 가이드에서는 인증, 첫 번째 요청, 스트리밍, 도구 호출, 그리고 Apidog를 사용한 통합 테스트에 대해 다룹니다.

소개

GLM-5.1은 Z.AI의 주력 에이전트 모델입니다. 2026년 4월에 출시되었습니다. SWE-Bench Pro에서 1위를 차지했으며, 모든 주요 코딩 벤치마크에서 GLM-5를 능가합니다. AI 코딩 도우미, 자율 에이전트 또는 장기적인 작업 실행의 이점을 얻는 애플리케이션을 구축 중이라면 GLM-5.1은 통합할 가치가 있습니다.

개발자들에게 좋은 소식은: 이 API는 OpenAI와 호환됩니다. 이미 GPT-4 또는 Claude를 기반으로 구축했다면, 기본 URL과 모델 이름만 변경하여 GLM-5.1로 전환할 수 있습니다. 새로운 SDK를 배울 필요도 없고, 다른 응답 형식을 처리할 필요도 없습니다.

사전 요구 사항

첫 번째 호출을 하기 전에 다음이 필요합니다:

1. bigmodel.cn의 BigModel 계정. 가입은 무료입니다.
2. API 키 섹션의 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"

소스 코드에 API 키를 하드코딩하지 마세요.

인증

모든 요청은 Authorization 헤더에 Bearer 토큰을 필요로 합니다:

Authorization: Bearer YOUR_API_KEY

BigModel API 키 형식은 xxxxxxxx.xxxxxxxxxxxxxxxx와 같이 점으로 구분된 두 부분으로 된 문자열입니다. 이는 OpenAI의 sk- 형식과는 다르지만 헤더에서는 동일하게 작동합니다.

기본 URL

https://open.bigmodel.cn/api/paas/v4/

채팅 완성 엔드포인트는 다음과 같습니다:

POST https://open.bigmodel.cn/api/paas/v4/chat/completions

첫 번째 요청

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
  }'

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"])

OpenAI SDK 사용 (권장)

API가 OpenAI와 호환되기 때문에, 사용자 지정 기본 URL과 함께 공식 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)

이것이 가장 깔끔한 접근 방식입니다. OpenAI SDK는 재시도, 타임아웃 관리 및 응답 파싱을 처리합니다. BigModel 기본 URL을 가리키는 것만으로도 이 모든 것을 무료로 얻을 수 있습니다.

응답 형식

응답 구조는 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
  }
}

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()  # newline after streaming completes

스트림의 각 청크는 이전 청크 이후의 새로운 토큰만 포함하는 델타입니다. 마지막 청크는 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)

도구 호출

GLM-5.1은 도구 호출을 지원합니다: 대화 중간에 함수 실행을 요청하는 기능입니다. 이는 모델이 코드를 실행하고, 데이터베이스를 검색하며, 외부 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}")

도구 호출 응답 처리

GLM-5.1이 도구 호출을 요청하면, 함수를 실행한 다음 다음 메시지에서 결과를 반환합니다:

import subprocess

def execute_tool(tool_call):
    """Execute the tool and return the result."""
    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):
    """Run a full agent loop with tool calling."""
    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":
            # Model is done
            return message.content

        if response.choices[0].finish_reason == "tool_calls":
            # Execute each tool call and add results
            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)

이 패턴은 에이전트 모델로서 GLM-5.1의 강점으로 직접 확장됩니다. 모델이 언제 도구를 호출할지, 결과를 처리할지, 그리고 해결책에 도달하거나 작업이 완료되었다고 판단할 때까지 계속하도록 할 수 있습니다.

주요 매개변수

코딩 작업에 권장되는 설정:

{
    "model": "glm-5.1",
    "temperature": 1.0,
    "top_p": 0.95,
    "max_tokens": 163840  # 장기 에이전트 실행을 위한 전체 컨텍스트
}

Z.AI는 자체 벤치마크 평가에서 이러한 설정을 사용합니다. 결정적인 코드 생성을 위해서는 온도를 0.2-0.4로 낮추세요.

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

Z.AI 코딩 플랜을 사용하면 BigModel API를 통해 Claude Code, Cline, Kilo Code 및 기타 AI 코딩 도우미를 GLM-5.1로 라우팅할 수 있습니다. 이는 Claude Opus 또는 GPT-5.4를 직접 실행하는 것보다 저렴한 비용으로 강력한 코딩 모델을 원할 때 유용합니다.

Claude Code 설정

Claude Code 구성 파일(~/.claude/settings.json 또는 이에 상응하는 파일)에서:

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

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"
}

할당량 소비

GLM-5.1은 토큰당 요금제가 아닌 Z.AI 할당량 시스템을 사용합니다: - 피크 시간 (UTC+8 14:00-18:00): 요청당 할당량 3배 - 비피크 시간: 요청당 할당량 2배 - 2026년 4월까지 프로모션 요금: 비피크 시간 동안 1배

과중한 에이전트 작업 부하의 경우, 장시간 실행되는 작업을 비피크 시간에 예약하세요. Z.AI가 시연한 600회 반복 최적화 실행은 피크 시간에 훨씬 더 많은 할당량을 소모합니다.

Apidog로 GLM-5.1 API 테스트

에이전트 API 통합을 테스트하려면 여러 응답 유형을 올바르게 처리해야 합니다: 일반 완성, 스트리밍 청크, 도구 호출 요청, 도구 결과 메시지, 그리고 오류 상태입니다. 이 모든 것을 실제 API를 대상으로 테스트하는 것은 할당량을 소모하고 실시간 연결을 필요로 합니다.

Apidog의 Smart Mock은 실제 API를 호출하지 않고도 이러한 모든 응답 상태를 정의하고 테스트할 수 있게 해줍니다.

모의(Mock) 엔드포인트 설정

1. Apidog에서 새 엔드포인트를 생성합니다: POST https://open.bigmodel.cn/api/paas/v4/chat/completions
2. 표준 성공 응답에 대한 모의 기대(Mock Expectation)를 추가합니다:

{
  "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
  }
}

1. 도구 호출 응답에 대한 두 번째 기대(expectation)를 추가합니다:

{
  "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
  }
}

1. 속도 제한 응답(HTTP 429)을 추가합니다:

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

전체 에이전트 루프 테스트

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의 테스트 시나리오는 변수를 사용하여 단계 간에 데이터를 전달할 수 있게 하므로, 1단계의 request_id 또는 tool_call_id 값은 자동으로 2단계로 전달됩니다. 이는 실제 에이전트 루프의 작동 방식을 반영하며 프로덕션 배포 전에 통합 버그를 잡아냅니다.

오류 처리

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

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")

개별 단계에 30-60초가 소요될 수 있는 긴 에이전트 실행의 경우, 항상 충분한 타임아웃(120-300초)을 설정하세요. 모델이 완전한 코드 파일을 생성하거나 복잡한 벤치마크 결과를 분석하는 데 시간이 필요할 수 있습니다.

결론

GLM-5.1의 OpenAI 호환 API는 GPT 또는 Claude를 이미 사용해본 경우 몇 분 만에 통합할 수 있음을 의미합니다. 주요 차이점은 엔드포인트(open.bigmodel.cn)와 토큰당 요금제가 아닌 할당량 시스템이라는 점입니다.

모델이 긴 세션 동안 수백 개의 도구 호출을 실행하는 에이전트 애플리케이션의 경우, GLM-5.1의 장기 최적화 기능은 진정한 장점입니다. 이를 Apidog의 Smart Mock 및 테스트 시나리오를 통한 적절한 테스트와 함께 사용하여 통합이 자율적으로 실행되기 전에 모든 엣지 케이스를 처리하는지 확인하세요.

GLM-5.1이 무엇이며 벤치마크가 어떻게 비교되는지에 대한 배경 지식은 GLM-5.1 모델 개요를 참조하세요. Apidog로 AI 에이전트 워크플로우를 구축하고 테스트하는 방법에 대한 자세한 내용은 AI 에이전트 메모리 작동 방식을 참조하세요.

자주 묻는 질문

GLM-5.1 API는 OpenAI와 호환됩니까?네. 요청 형식, 응답 구조, 스트리밍 프로토콜 및 도구 호출 형식은 모두 OpenAI 채팅 완성 API와 동일합니다. 기본 URL을 https://open.bigmodel.cn/api/paas/v4/로 설정하여 공식 OpenAI Python SDK 또는 모든 OpenAI 호환 클라이언트를 사용할 수 있습니다.

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 이상)으로 설정하여 작업 중간에 모델의 출력이 잘리는 것을 방지하세요.

GLM-5.1을 함수 호출/도구 사용에 사용할 수 있습니까?네. GLM-5.1은 OpenAI API와 동일한 도구 호출 형식을 지원합니다. type: "function" 스키마를 사용하여 도구를 정의하고, 이를 tools 배열에 전달하며, 에이전트 루프에서 finish_reason: "tool_calls" 응답을 처리합니다.

할당량을 소모하지 않고 GLM-5.1 API 호출을 테스트하려면 어떻게 해야 합니까?Apidog의 Smart Mock을 사용하여 각 API 상태에 대한 모의 응답을 정의하세요: 성공, 도구 호출, 속도 제한, 오류. 개발 중에는 모의(mock)를 대상으로 테스트 스위트를 실행하고, 최종 유효성 검사를 위해서만 실제 API를 사용하세요.

GLM-5.1 모델 가중치는 어디서 찾을 수 있습니까?오픈소스 가중치는 HuggingFace의 zai-org/GLM-5.1에 있습니다. MIT 라이선스에 따라 출시되었으며 로컬 추론을 위해 vLLM 및 SGLang을 지원합니다.