> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# GLM Chat Completion API 申請及使用

> GLM 整合指南 - Ace Data Cloud

GLM（General Language Model）是智譜 AI（Zhipu AI / Z.ai）推出的新一代大語言模型系列，具備強大的中英文理解與生成能力，在中文場景、代碼生成、推理與多輪對話等任務上都有出色表現。GLM-5.3、GLM-5.2、GLM-4.7 等新一代模型在長上下文、工具調用與代碼任務上做了大量優化，可廣泛應用於智能問答、內容創作、代碼輔助、客服機器人等場景。

本文檔主要介紹 GLM Chat Completion API 的使用流程，利用它您可以通過統一的 OpenAI 兼容接口輕鬆調用 GLM 系列模型。

## 申請流程

要使用 GLM Chat Completion API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。

**一個 API Token 即可調用平台所有服務，無需為每個服務單獨申請。** 首次申請會贈送免費額度，可免費體驗；額度不足時可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用餘額。

> 📘 完整文檔：[GLM Chat Completion API →](https://platform.acedata.cloud/documents/glm-chat-completions)

## 基本使用

GLM Chat Completion API 的請求地址為 `https://api.acedata.cloud/glm/chat/completions`，使用 Bearer Token 鑒權，請求體兼容 OpenAI Chat Completions 協議。

在第一次使用該接口時，我們至少需要填寫三個內容：

* `authorization`：直接在下拉列表裡面選擇 Bearer Token 即可。
* `model`：選擇要調用的 GLM 模型，目前支持的模型包括：
  * `glm-5.3`：最新旗艦模型，支持 1M 上下文與最長 128K 輸出，適合複雜推理、代碼與 Agent 任務。推理始終開啟，可通過 `reasoning_effort` 選擇 `low`、`high` 或 `max`。
  * `glm-5.2`：上一代旗艦模型，綜合能力強。
  * `glm-5.1`：成熟旗艦模型，適合通用複雜任務。
  * `glm-4.7`：在推理、工具調用與代碼任務上表現優秀。
  * `glm-4.6`：通用對話模型，平衡效果與成本。
  * `glm-3-turbo`：經典對話模型，適用於一般文本生成任務。
* `messages`：提示詞數組，每條消息包含 `role` 和 `content`，`role` 支持 `user`、`assistant`、`system` 三種角色。

常用可選參數：

* `max_tokens`：限制單次回覆的最大 token 數。
* `temperature`：生成隨機性，0-2 之間，值越大越發散。
* `top_p`：核採樣參數，控制候選 token 的累積概率閾值。
* `n`：一次生成多少條候選回覆。
* `stream`：是否啟用流式響應，默認 `false`。
* `stop`：自定義停止序列。

下面是一個最簡單的 Python 調用示例：

```python theme={null}
import requests

url = "https://api.acedata.cloud/glm/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "glm-5.2",
    "messages": [
        {"role": "user", "content": "hello"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

調用之後，我們發現返回結果如下：

```json theme={null}
{
  "id": "msg_202604262252030313862701a04e33",
  "model": "glm-5.2",
  "object": "chat.completion",
  "created": 1777215124,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! 👋 How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 23,
    "total_tokens": 33
  }
}
```

返回結果各主要字段說明如下：

* `id`：本次對話任務的唯一 ID。
* `created`：本次對話任務的創建時間（Unix 時間戳，秒）。
* `model`：實際調用的 GLM 模型名稱。
* `choices`：模型生成的回覆列表。`choices[i].message.content` 即模型回覆的具體文本，`finish_reason` 標識結束原因（`stop`、`length`、`tool_calls`、`content_filter` 等）。
* `usage`：本次請求的 token 用量統計，包含 `prompt_tokens`、`completion_tokens`、`total_tokens`。

## 流式響應

該接口支持流式響應（Server-Sent Events），這對網頁對接十分有用，可以讓網頁實現逐字顯示效果。

如果想流式返回響應，將請求體中的 `stream` 參數設置為 `true` 即可。

Python 樣例調用代碼：

```python theme={null}
import requests

url = "https://api.acedata.cloud/glm/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "hi"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))
```

輸出效果如下（節選）：

```text theme={null}
data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "", "role": "assistant"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "你好！有什么我可以"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "帮助你的"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "吗？"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {}, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [], "usage": {"prompt_tokens": 1420, "completion_tokens": 18, "total_tokens": 1438}}

data: [DONE]
```

可以看到，响应里面有许多 `data`，每条 `data` 包含一个增量片段。`choices[i].delta.content` 是当前 chunk 新增的文本片段，您可以将这些片段拼接起来形成完整回复。当 `data` 内容为 `[DONE]` 时表示流式响应结束。最后一条带 `usage` 的 chunk 会汇总本次请求的 token 用量。

JavaScript（Node.js）样例：

```javascript theme={null}
const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "glm-4.7",
    messages: [{ role: "user", content: "hi" }],
    stream: true
  })
};

const response = await fetch("https://api.acedata.cloud/glm/chat/completions", options);
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}
```

Java 样例代码：

```java theme={null}
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "glm-4.7");
jsonObject.put("messages", new JSONArray().put(new JSONObject().put("role", "user").put("content", "hi")));
jsonObject.put("stream", true);
MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
RequestBody body = RequestBody.create(jsonObject.toString(), mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/glm/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
```

其他语言可以另外自行改写，原理都是一样的。

## 多轮对话

如果您想要实现多轮对话功能，需要将历史对话依次放入 `messages` 数组，并保留 `user` 与 `assistant` 交替出现的顺序。

Python 样例调用代码：

```python theme={null}
import requests

url = "https://api.acedata.cloud/glm/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hi! How can I assist you today?"},
        {"role": "user", "content": "What did I say just now?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

通过上传多个提问词，就可以轻松实现多轮对话，可以得到如下回答：

```json theme={null}
{
  "id": "msg_20260426225208b95324e9945a48d3",
  "model": "glm-4.7",
  "object": "chat.completion",
  "created": 1777215128,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你说：**\"Hello\"** 😊\n\n如果你需要其他帮助，请告诉我！"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 37,
    "total_tokens": 85
  }
}
```

可以看到，`choices` 包含的信息与基本使用一致，模型基于完整的对话历史给出回复，从而支持多轮上下文交互。

## 系统提示词（System Prompt）

可以在 `messages` 的开头添加一条 `role` 为 `system` 的消息，用来约束模型的角色、风格或行为：

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "system", "content": "你是一名资深的中文写作助手，请用简洁专业的语气回复。"},
        {"role": "user", "content": "请用三句话介绍一下 GLM 模型。"}
    ]
}
```

## 工具调用（Function Calling）

GLM 模型支持 OpenAI 兼容的 Function Calling，可以通过 `tools` 参数声明可调用的函数，模型在需要时会在 `choices[i].message.tool_calls` 中返回结构化的函数调用信息。

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "user", "content": "北京今天天气怎么样？"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "查询指定城市的天气",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "城市名称"}
                    },
                    "required": ["city"]
                }
            }
        }
    ]
}
```

模型如果决定调用工具，返回结果中 `finish_reason` 会变为 `tool_calls`，并在 `message.tool_calls` 中给出函数名和 JSON 字符串形式的参数。您可以执行该函数并将结果作为 `role` 为 `tool` 的消息回传给模型，从而完成完整的工具调用回路。

## 模型选择建议

| 模型 | 适用场景 |
| - | - |
| `glm-5.3` | 最新旗舰，1M 上下文、最长 128K 输出，推荐用于复杂推理、代码与 Agent 任务 |
| `glm-5.2` | 上一代旗舰，适合复杂推理、代码与 Agent 任务 |
| `glm-5.1` | 成熟旗舰，适合复杂推理、长文档分析 |
| `glm-4.7` | 工具调用、代码生成、Agent 编排等任务 |
| `glm-4.6` | 通用对话、内容创作的均衡选择 |
| `glm-3-turbo` | 一般文本生成任务，对成本敏感的场景 |

## 错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

* `400 token_mismatched`：请求参数缺失或无效。
* `400 api_not_implemented`：使用了不被支持的参数或模型。
* `401 invalid_token`：未授权，Bearer Token 缺失或失效。
* `429 too_many_requests`：触发频率限制，请稍后重试。
* `500 api_error`：服务器内部错误或上游暂时不可用。

### 错误响应示例

```json theme={null}
{
  "trace_id": "69ea9bcf-c5da-41a3-be97-c80912a08523",
  "error": {
    "code": "api_error",
    "message": "服务暂时不可用，请稍后重试。"
  }
}
```

当返回 `api_error` 且消息为 `服务暂时不可用，请稍后重试。` 时，通常表示上游 GLM 服务暂时不可用，建议带指数退避重试，或切换到其他可用的 GLM 模型（例如从 `glm-5.1` 临时切换到 `glm-4.7` 或 `glm-4.6`）。

## 结论

通过本文档，您已经了解了如何使用 GLM Chat Completion API 调用智谱 AI 的 GLM 系列模型，包括基本调用、流式响应、多轮对话、系统提示词与工具调用等典型用法。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.