ÖZET
GLM-5.1'e BigModel API üzerinden https://open.bigmodel.cn/api/paas/v4/ adresinden erişebilirsiniz. API, OpenAI ile tamamen uyumludur: aynı uç nokta yapısı, istek formatı ve akış paterni. Bir BigModel hesabı, API anahtarı ve glm-5.1 model adına ihtiyacınız var. Bu rehberde kimlik doğrulama, ilk API çağrısı, akışlı cevaplar, araç çağırma ve Apidog ile entegrasyon testi adım adım anlatılmaktadır.
Giriş
GLM-5.1, Z.AI'nin amiral gemisi ajan modeli Nisan 2026'da piyasaya sürüldü. SWE-Bench Pro'da 1 numarada yer alır ve tüm büyük kodlama kıyaslamalarında GLM-5’in önündedir. Eğer bir yapay zeka kodlama asistanı, özerk ajan veya uzun vadeli görevler yürüten bir uygulama geliştiriyorsanız GLM-5.1'i entegre etmek mantıklıdır.
Geliştiriciler için avantaj: API, OpenAI ile uyumludur. GPT-4 veya Claude ile çalıştıysanız sadece temel URL ve model adını değiştirerek GLM-5.1'e geçebilirsiniz. Yeni bir SDK öğrenmenize veya farklı bir yanıt formatıyla uğraşmanıza gerek yok.
💡 Ajan API’lerinde en büyük zorluk: Test. Yüzlerce araç çağrısını çalıştırmak ve gerçek API'ye karşı test yapmak kota tüketir. Apidog’un Test Senaryoları ile ajanınızın yaptığı istekleri sıralayabilir, her durum için yanıtları taklit edebilir ve entegrasyonunuzun akış, araç çağrıları ve hata koşullarını üretimden önce doğrulayabilirsiniz. Test bölümünü uygulamak için Apidog’u ücretsiz indirebilirsiniz.
Önkoşullar
İlk çağrınızı yapmadan önce aşağıdakilere ihtiyacınız var:
- bigmodel.cn üzerinde BigModel hesabı (ücretsiz kayıt).
- BigModel konsolunda API anahtarı (API Keys altından alınır).
- Python 3.8+ veya Node.js 18+ (örnekler ikisini de kapsar).
-
OpenAI SDK veya standart
requests/fetch(API, OpenAI ile uyumludur).
API anahtarınızı ortam değişkeni olarak ayarlayın:
export BIGMODEL_API_KEY="your_api_key_here"
API anahtarlarını kaynak koduna sabit yazmayın.
Kimlik Doğrulama
Her istek şu başlığı içerir:
Authorization: Bearer YOUR_API_KEY
BigModel API anahtarı, iki parçalı bir dizedir: xxxxxxxx.xxxxxxxxxxxxxxxx. OpenAI'nin sk- formatından farklıdır ama başlıkta aynı şekilde kullanılır.
Temel URL
https://open.bigmodel.cn/api/paas/v4/
Sohbet tamamlamaları uç noktası:
POST https://open.bigmodel.cn/api/paas/v4/chat/completions
İlk İsteğiniz
Curl Kullanımı
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 Kullanımı (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 Kullanımı (Önerilir)
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 ile yeniden deneme, zaman aşımı ve yanıt ayrıştırma ücretsiz şekilde gelir. Tek yapmanız gereken BigModel temel URL’sini tanımlamaktır.
Yanıt Formatı
Yanıt yapısı OpenAI ile aynıdır:
{
"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
}
}
Yanıt metnine result["choices"][0]["message"]["content"] ile erişin.
usage alanı token sayılarını gösterir. GLM-5.1, zirve saatlerde (14:00-18:00 UTC+8) 3 kat kota kullanır; bu nedenle kota tüketiminizi izleyin.
Akışlı Yanıtlar
Uzun kod üretimi için akış, yanıtı beklemeden token'ları gelirse gösterir. Kullanıcıya dönük uygulamalar için önerilir.
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() # akış tamamlandıktan sonra yeni satır
Her parça, son parçadan bu yana yeni token’ları getirir. Son parçada finish_reason "stop" (veya token limitine ulaşırsanız "length") olur.
Ham İsteklerle Akış
OpenAI SDK kullanmazsanız:
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)
Araç Çağırma
GLM-5.1, OpenAI ile aynı araç çağırma (function calling) formatını destekler. Konuşma sırasında fonksiyon yürütme istekleri göndermek için kullanılır.
Araçları Tanımlama
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}")
Araç Çağırma Yanıtlarını İşleme
Model araç çağırdığında, fonksiyonu yürütüp sonucu bir sonraki mesajda döndürmelisiniz:
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)
Bu desen, GLM-5.1’in ajanik model olarak tam potansiyelini kullanır. Modelin araçları ne zaman çağıracağına, sonuçları işleyip bir çözüme ulaşana kadar devam etmesine izin verirsiniz.
Anahtar Parametreler
| Parametre | Tip | Varsayılan | Açıklama |
|---|---|---|---|
model |
string | gerekli |
"glm-5.1" kullanın |
messages |
dizi | gerekli | Konuşma geçmişi |
max_tokens |
integer | 1024 | Üretecek maksimum token (163.840'a kadar) |
temperature |
float | 0.95 | Rastgelelik. 0.0-1.0 arası |
top_p |
float | 0.7 | Çekirdek örnekleme. Kodlama için 0.7 önerilir |
stream |
boolean | false | Akışlı yanıtlar için true |
tools |
dizi | null | Araç fonksiyon tanımları |
tool_choice |
string/object | "auto" | "auto", "none" veya spesifik araç |
stop |
string/array | null | Özel durdurma dizileri |
Kodlama görevleri için önerilen ayarlar:
{
"model": "glm-5.1",
"temperature": 1.0,
"top_p": 0.95,
"max_tokens": 163840 # uzun ajanik çalıştırmalar için
}
Deterministik kod üretimi için temperature değerini 0.2-0.4'e çekin.
GLM-5.1'i Kodlama Asistanları ile Kullanma
Z.AI Kodlama Planı, Claude Code, Cline, Kilo Code gibi AI kodlama asistanlarını BigModel API üzerinden GLM-5.1 ile çalıştırmanızı sağlar. Güçlü bir kodlama modeli kullanmak isteyenler için faydalıdır.
Claude Code Kurulumu
Konfigürasyon dosyanızda (~/.claude/settings.json):
{
"model": "glm-5.1",
"baseURL": "https://open.bigmodel.cn/api/paas/v4/",
"apiKey": "your_bigmodel_api_key"
}
Cline / Roo Code Kurulumu
VS Code ayarlarında veya Cline uzantı konfigürasyonunda:
{
"cline.apiProvider": "openai",
"cline.openAIBaseURL": "https://open.bigmodel.cn/api/paas/v4/",
"cline.openAIApiKey": "your_bigmodel_api_key",
"cline.openAIModelId": "glm-5.1"
}
Kota Tüketimi
GLM-5.1, Z.AI kota sistemiyle çalışır:
- Zirve saatler (14:00-18:00 UTC+8): istek başına 3 kat kota
- Zirve dışı: istek başına 2 kat kota
- Nisan 2026 sonuna kadar promosyon: zirve dışı saatlerde 1 kat kota
Uzun süreli görevleri zirve dışı saatlere planlayarak kota maliyetinizi düşürün.
GLM-5.1 API’sini Apidog ile Test Etme
Bir ajanik API entegrasyonunu test etmek için birçok yanıt türünü (tamamlama, akış, araç çağrısı, hata) işlemeniz gerekir. Gerçek API'ye karşı test kota tüketir.
Apidog’un Akıllı Sahte (Smart Mock) özelliğiyle tüm bu yanıtları tanımlayın, kota harcamadan test edin.
Sahte Uç Nokta Kurulumu
- Apidog’da yeni bir uç nokta oluşturun:
POST https://open.bigmodel.cn/api/paas/v4/chat/completions - Başarı yanıtı için bir Sahte Beklenti ekleyin:
{
"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
}
}
- Araç çağrısı yanıtı için ikinci bir beklenti:
{
"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
}
}
- Hız sınırı (HTTP 429) yanıtı:
{
"error": {
"message": "Rate limit exceeded. Please retry after 60 seconds.",
"type": "rate_limit_error",
"code": "rate_limit_exceeded"
}
}
Tam Ajan Döngüsü Testi
Apidog’un Test Senaryoları ile zincirleme testler kurabilirsiniz:
-
Adım 1: Başlangıç mesajı ile
/chat/completions'a POST yapın, 200 vefinish_reason == "tool_calls"doğrulayın. -
Adım 2: Araç sonucuyla tekrar POST yapın, 200 ve
finish_reason == "stop"doğrulayın. - Adım 3: Son içeriği çıkarın ve beklenen kodu içerdiğini kontrol edin.
Bu şekilde kota harcamadan tam ajan döngüsünü test edebilirsiniz. Sahteyi 429 döndürecek şekilde değiştirerek hata işlemeyi de sınayabilirsiniz.
Çok adımlı iş akışlarında, Apidog Test Senaryoları sayesinde adımlar arası veri aktarımı otomatik gerçekleşir (request_id, tool_call_id gibi değerler). Bu, gerçek bir ajan döngüsünü simüle eder ve entegrasyon hatalarını canlıya çıkmadan yakalamanızı sağlar.
Hata Yönetimi
API standart HTTP durum kodlarını döndürür:
| Durum | Anlamı | Eylem |
|---|---|---|
| 200 | Başarılı | Yanıtı işleyin |
| 400 | Hatalı istek | İstek formatınızı kontrol edin |
| 401 | Yetkisiz | API anahtarınızı doğrulayın |
| 429 | Hız sınırı |
Retry-After başlığı kadar bekleyip tekrar deneyin |
| 500 | Sunucu hatası | Üstel geri çekilme ile tekrar deneyin |
| 503 | Servis kullanımda | Üstel geri çekilme ile tekrar deneyin |
Otomatik tekrar ve zaman aşımı için örnek kod:
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")
Uzun ajanik çalıştırmalarda zaman aşımını 120-300 saniye gibi cömert bir değere ayarlayın. Modelin tam kod dosyası üretmesi veya karmaşık analiz yapması zaman alabilir.
Sonuç
GLM-5.1’in OpenAI ile uyumlu API’si, GPT veya Claude ile çalıştıysanız hızlı entegrasyon sağlar. Temel farklılıklar: uç nokta (open.bigmodel.cn) ve kota bazlı faturalandırma sistemidir.
Uzun oturumlu, çok adımlı ve araç kullanan ajanik uygulamalar için GLM-5.1’in optimizasyon kapasitesi büyük avantaj sunar. Entegrasyonunuzun tüm durumlarını üretime çıkmadan önce Apidog’un Akıllı Sahte ve Test Senaryoları ile detaylıca test edin.
GLM-5.1’in detayları ve karşılaştırması için GLM-5.1 model genel bakışına bakabilirsiniz. Apidog ile AI ajan iş akışları oluşturma ve test etme hakkında daha fazla bilgi için AI ajan belleği nasıl çalışır yazısını inceleyin.
Sıkça Sorulan Sorular
GLM-5.1 API'si OpenAI ile uyumlu mu?
Evet. İstek formatı, yanıt yapısı, akış protokolü ve araç çağırma formatı OpenAI sohbet tamamlamaları API’siyle tamamen aynıdır. Temel URL’yi https://open.bigmodel.cn/api/paas/v4/ olarak ayarlayarak resmi OpenAI Python SDK’sı veya herhangi bir OpenAI uyumlu istemciyle kullanabilirsiniz.
API isteklerinde kullanılacak model adı nedir?
Sadece "glm-5.1" kullanın.
GLM-5.1 API fiyatlandırması nasıl çalışır?
BigModel API kota ile çalışır. GLM-5.1, zirve saatlerinde (14:00-18:00 UTC+8) 3 kat, zirve dışı saatlerde 2 kat kota tüketir. Nisan 2026 sonuna kadar promosyon ile zirve dışı kullanımda 1 kat kota kullanılır.
Maksimum bağlam uzunluğu nedir?
200.000 token giriş bağlamı, maksimum çıktı 163.840 token’dır. Uzun çalışmalar için max_tokens’ı yüksek ayarlayın.
GLM-5.1’i fonksiyon çağırma/araç kullanımı için kullanabilir miyim?
Evet. OpenAI ile aynı araç çağırma formatı desteklenir. Araçları type: "function" şemasıyla tanımlayın, tools dizisine ekleyin ve finish_reason: "tool_calls" yanıtlarını işleyin.
Kota harcamadan GLM-5.1 API çağrılarını nasıl test ederim?
Her API durumu için Apidog’un Akıllı Sahte özelliğiyle yanıtlar tanımlayın. Test paketinizi sahteye karşı çalıştırın, sadece son doğrulama için gerçek API’yi kullanın.
GLM-5.1 model ağırlıklarını nerede bulabilirim?
Açık kaynak ağırlıklar HuggingFace’te zai-org/GLM-5.1 adresinde. MIT Lisansı altında yayınlanmıştır ve vLLM, SGLang ile yerel çıkarım desteklenir.
Top comments (0)