Zhipuai API: hosted inference and integration patterns

The Zhipuai API contract

The Zhipuai API mirrors the OpenAI chat-completions contract closely enough that most existing integrations require only a base URL change and a key swap to begin working.

The Zhipuai API is the hosted inference endpoint for the GLM model family, managed through the BigModel open platform. At the chat-completions level, the request and response shapes are OpenAI-compatible: the same message array format, the same role labels (system, user, assistant), the same streaming flag, and the same response envelope. This compatibility is intentional — the Zhipu AI team designed the API surface to minimise switching friction for teams already operating against the OpenAI endpoint.

The practical implication is that any code using the openai Python package or the openai Node package can be redirected to the Zhipuai API with two changes: base_url set to the BigModel endpoint and api_key set to a key obtained from the BigModel console. All method calls, parameter names, response parsing, and error handling patterns remain identical for the basic chat-completions use case. Teams that have built wrapper layers around the OpenAI SDK for logging, retry logic, or prompt templating typically find that the wrapper continues to work without modification.

Base URL and SDK configuration

A one-line change to base_url is all that most existing OpenAI SDK integrations need to start hitting the Zhipuai API endpoint.

The BigModel endpoint base URL follows the pattern https://open.bigmodel.cn/api/paas/v4/ for the current API version. The trailing slash is required by the SDK's path construction; omitting it produces a malformed endpoint URL on some SDK versions. The Python and Node SDK snippets below illustrate the complete configuration for chat completions. Note that these snippets use placeholder key strings — substitute your actual key from the BigModel console.

Python example

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_ZHIPUAI_KEY_HERE",
    base_url="https://open.bigmodel.cn/api/paas/v4/"
)

response = client.chat.completions.create(
    model="glm-4",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain rate limiting in one paragraph."}
    ],
    temperature=0.7,
    max_tokens=512
)
print(response.choices[0].message.content)

Node.js example

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZHIPUAI_KEY,
  baseURL: "https://open.bigmodel.cn/api/paas/v4/"
});

const response = await client.chat.completions.create({
  model: "glm-4",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain streaming in one paragraph." }
  ],
  stream: false
});
console.log(response.choices[0].message.content);

Rate limits

Rate limits on the Zhipuai API are applied at the request-per-minute and token-per-minute level, with values that scale across billing tiers.

The Zhipuai API enforces two parallel rate limit dimensions: requests per minute (RPM) and tokens per minute (TPM). The free trial tier applies conservative limits on both axes — enough for feature testing and small prompt evaluations, but not enough for batch workloads or concurrent multi-user applications. Paid tiers raise both limits substantially; the current values for each tier are published in the BigModel console and are also readable from the X-RateLimit-Requests-Limit, X-RateLimit-Requests-Remaining, and X-RateLimit-Requests-Reset response headers on each API call. Implementing header-driven back-off in your client is more reliable than hardcoding sleep intervals, because tier limits can change without notice.

When a rate limit is exceeded, the Zhipuai API returns HTTP 429 with a structured error body. The retry_after field in the error response specifies the number of seconds to wait before the next attempt is likely to succeed. Clients should respect this value rather than retrying immediately, which would keep triggering 429 responses and extend the effective blackout window.

Error codes

The Zhipuai API error taxonomy follows the OpenAI convention closely, making it straightforward to handle in existing error-handling middleware.

The Zhipuai API returns standard HTTP status codes with structured JSON error bodies. The error object in the response body includes a code string, a message string, and a type string. Common codes include invalid_api_key (401), model_not_found (404), rate_limit_exceeded (429), and internal_server_error (500). The 500 class errors are transient — a short exponential back-off with two or three retries resolves the majority of them without human intervention.

Billing tiers

The Zhipuai API bills per token at rates that vary by model variant — the pricing page on this site documents the current tiers.

Zhipuai API billing is per token, with separate input and output token rates for each model variant. The general-purpose GLM-4.5+ tier is priced higher than the smaller GLM variants; the code-specialised variant sits between them. The BigModel console shows a live usage dashboard with daily and monthly breakdowns by model and project. Spend alerts can be configured to notify at a threshold before the hard limit is reached. The Z.ai pricing page on this site walks through the per-token tiers for each model class in more detail.

Guidance from AI.gov on responsible AI procurement is a useful reference for teams formalising their vendor evaluation and API usage governance processes before committing to production.

Zhipuai API key parameters

Six parameters cover the majority of practical API usage — a quick reference for parameter name, type, default value, and notes.

Practitioner note

"Migrating our internal toolchain from the OpenAI endpoint to the Zhipuai API took an afternoon. The base_url swap was the entire change; the rest of the integration layer — retry logic, response parsing, prompt templates — ran without a single modification."