Integrating the GLM API costs less effort than many people expect. It offers an OpenAI-compatible interface, so an existing OpenAI SDK usually needs only three changes: the API key, the base URL, and the model name. The real pitfalls are not "can it connect at all," but whether the model name is valid, how to handle streaming output, what format tool calls return, and which parameters cannot be copied over from OpenAI.
This article gets the whole chain working with one minimal request, then adds streaming, tool calls, error troubleshooting, and a migration checklist. Every example can be run directly after you replace the key.
Note: Zhipu, GLM, and BigModel are trademarks of their respective owners. This article is for technical explanation only and implies no affiliation, agency, or endorsement relationship with Zhipu. Base URLs, model names, context lengths, and billing rules may change. Follow the official Zhipu open platform documentation and the model pricing page.
1. Before you start
Confirm three things before starting:
- A usable API key whose type matches the interface you want to call.
- The correct base URL. Official direct access and gateway addresses cannot be mixed.
- A model name that is actually available today. Do not copy examples from old articles.
For a new project, verify authentication and network connectivity with curl before wiring in an SDK. When something fails, it is then much easier to tell whether the problem is the key, the address, or the code.
2. How to fill in the base URL
The base URL for Zhipu's official OpenAI-compatible interface is usually written as:
https://open.bigmodel.cn/api/paas/v4
The OpenAI-compatible address for the ZSQH AI Gateway is:
https://ai.zhongshangqihang.com/v1
Both append OpenAI's /chat/completions path. Do not repeat the version segment or /chat/completions in your code, and do not mix trailing-slash variants within the same project.
| Access method | Example base URL | Suitable for | Cautions |
|---|---|---|---|
| Zhipu official | https://open.bigmodel.cn/api/paas/v4 |
GLM only, newest features | Requires an official account and balance |
| ZSQH gateway | https://ai.zhongshangqihang.com/v1 |
One entry point and one bill for several models | Create a key on the gateway |
3. How to choose a model name
The GLM family is divided into text, vision, speech, embedding, and other categories. Text models come in different tiers: some favor general conversation and agents, some favor low latency and high concurrency, and some support longer context. Taking the GLM-5 series currently listed in the official documentation as an example, common names include glm-5.3, glm-5.3-flash, and glm-5.2, but models are updated continuously. The names actually available are determined by the console and the model pricing page.
Do not choose only by "most powerful." For tasks such as customer-service Q&A and bulk classification, a low-latency tier is often more economical. For long-document analysis and complex agents, move up to a higher configuration. Make the model name a configuration item rather than hard-coding it, so later switches are much easier.
If the task involves image understanding, choose a model that accepts visual input. For vector retrieval, use the embedding family. Text, vision, and embedding models do not share exactly the same endpoints and parameters, so do not force the same request body onto all of them. Before launch, put candidate models through the same evaluation set, compare accuracy, latency, and usage, and then decide on the primary and fallback models.
4. Make the first call with curl
Set environment variables first so the key does not appear in command history:
export GLM_API_KEY="your_key_here"
curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
-H "Authorization: Bearer $GLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an API gateway is in three sentences."}
],
"temperature": 0.6
}'
When the response is normal, focus on three fields: choices[0].message.content is the answer, usage is the consumption for this request, and finish_reason indicates why generation ended. If you get a 401, check the key and headers first. If you get 1211, check the model name first.
5. Calling with the Python SDK and streaming
The OpenAI SDK must be version 1.0 or later. Point the base URL at GLM and the call looks almost identical to OpenAI:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("GLM_API_KEY"),
base_url="https://open.bigmodel.cn/api/paas/v4",
)
stream = client.chat.completions.create(
model="glm-5.3",
messages=[{"role": "user", "content": "Write a product introduction under one hundred words."}],
stream=True,
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
Streaming has a few details worth noting. The first chunk may contain only role information, with an empty content, so never assume every chunk carries text. When thinking mode is enabled, reasoning may appear in the reasoning_content field while the final answer remains in content. Handle the two separately, and avoid showing the reasoning process directly to end users.
6. Tool calls and parameter differences
Tool calls use OpenAI's tools and tool_choice format. After the model returns message.tool_calls, parse each call's function.arguments as JSON, execute the local function, and send the result back as a tool-role message. In production, validate arguments and enforce timeouts. Never trust model-generated arguments directly.
When migrating from OpenAI, keep several differences in mind: the temperature range is usually between 0 and 1, passing 0 may not take effect, the default is about 0.6, and some newer capabilities require parameters passed through extra_body. The official OpenAI-compatible documentation is the authority for exact parameters.
Streaming also requires handling client disconnects. After a user closes the page, the server should cancel the upstream request as soon as possible to avoid continued generation and billing. If the business requires the full output, move the task to a background queue rather than depending on the frontend connection.
7. Common error reference
| Symptom | Likely cause | What to do |
|---|---|---|
| 401 / 1000 | Wrong key or mismatched key type | Check the key type and request header |
| 1211 | Model name does not exist or is not enabled | Check available models in the console |
| 1261 | Input exceeds the context limit | Compress the prompt or split it |
| 1302 / 1305 | Account rate limit or platform busy | Reduce concurrency, back off, retry |
| 1113 | Account in arrears | Top up and retry |
| Connection timeout | DNS, proxy, or network path | Use curl first to isolate the network layer |
Retries help only for 429, 5xx, and network timeouts. Errors such as 401, 1211, and 1261 do not improve with retries; retrying only wastes time and quota.
8. Migration checklist from OpenAI
- Back up existing prompts, model parameters, and evaluation sets.
- Create a dedicated GLM key; do not reuse another vendor's key.
- Move the base URL and model name into configuration.
- Compare output quality, latency, and usage on the same sample set.
- Check compatibility of streaming parsing, tool calls, and JSON output.
- Adjust retries, timeouts, and concurrency, and observe for a week before switching all traffic.
9. FAQ
1. Is the GLM API fully OpenAI-compatible?
Most commonly used interfaces are compatible, but differences remain in parameter ranges, thinking fields, and some advanced capabilities. Verify item by item against the official OpenAI-compatible documentation instead of assuming all parameter behavior is identical.
2. Should the base URL end with a slash?
Both forms appear in official documentation, and SDKs usually handle either. The key point is not to repeat path segments. Choose one form and use it consistently throughout the project.
3. Can streaming output include the reasoning process?
Some models return reasoning_content in thinking mode. Whether to display it depends on product design; for end users, usually only the final answer is shown.
4. Is the tool-call format the same as OpenAI's?
Tool definitions and response structures largely follow the OpenAI format, but parameter details can change with the model. Run a regression test with real tools before launch.
5. Are model names the same on the official platform and the gateway?
Most names are shared, but whether the gateway has enabled a given model or supports a given parameter depends on the gateway console and the model pricing page.
