> ## 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 API guide - Ace Data Cloud

GLM (General Language Model) — это новое поколение серии больших языковых моделей, выпущенное Zhipu AI (智谱 AI / Z.ai), обладающее мощными способностями понимания и генерации как на китайском, так и на английском языках, демонстрируя отличные результаты в задачах, связанных с китайскими сценами, генерацией кода, выводами и многократными диалогами. Новые модели, такие как GLM-5.3, GLM-5.2, GLM-4.7, были значительно оптимизированы для работы с длинными контекстами, вызовами инструментов и задачами кода и могут широко применяться в таких сценариях, как интеллектуальные вопросы и ответы, создание контента, помощь в кодировании, чат-боты и т.д.

В этом документе в основном описывается процесс использования GLM Chat Completion API, с помощью которого вы можете легко вызывать модели серии GLM через единый совместимый интерфейс OpenAI.

## Процесс заявки

Чтобы использовать 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`: ограничение на максимальное количество токенов в одном ответе.
* `temperature`: случайность генерации, от 0 до 2, чем больше значение, тем более разнообразным будет ответ.
* `top_p`: параметр ядерной выборки, контролирующий порог накопленной вероятности кандидатов токенов.
* `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`: статистика использования токенов для текущего запроса, включает `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` — это текущий новый текстовый фрагмент, который вы можете соединить, чтобы сформировать полный ответ. Когда содержимое `data` равно `[DONE]`, это означает, что потоковый ответ завершен. Последний фрагмент с `usage` подводит итог использованию токенов в этом запросе.

Пример на 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: "привет" }],
    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", "привет")));
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": "Привет"},
        {"role": "assistant", "content": "Привет! Как я могу помочь вам сегодня?"},
        {"role": "user", "content": "Что я только что сказал?"}
    ]
}

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": "Вы сказали: **\"Привет\"** 😊\n\nДайте знать, если вам нужно что-то еще!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 37,
    "total_tokens": 85
  }
}
```

Можно увидеть, что информация, содержащаяся в `choices`, соответствует основному использованию, модель дает ответ на основе полной истории диалога, поддерживая многоуровневое взаимодействие в контексте.

## Системные подсказки (System Prompt)

Вы можете добавить сообщение с `role` равным `system` в начале `messages`, чтобы ограничить роль, стиль или поведение модели:

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "system", "content": "Вы опытный помощник по написанию на китайском языке, пожалуйста, отвечайте кратко и профессионально."},
        {"role": "user", "content": "Пожалуйста, расскажите о модели GLM в трех предложениях."}
    ]
}
```

## Вызов функций (Function Calling)

Модель GLM поддерживает совместимый с OpenAI вызов функций, вы можете объявить вызываемые функции через параметр `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"]
                }
            }
        }
    ]
}
```

Если модель решит вызвать инструмент, причина завершения в результате изменится на `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`：Внутренняя ошибка сервера или временная недоступность upstream.

### Пример ответа об ошибке

```json
{
  "trace_id": "69ea9bcf-c5da-41a3-be97-c80912a08523",
  "error": {
    "code": "api_error",
    "message": "Сервис временно недоступен, пожалуйста, попробуйте позже."
  }
}
````

Когда возвращается `api_error` и сообщение `Сервис временно недоступен, пожалуйста, попробуйте позже.`, это обычно означает, что upstream GLM сервис временно недоступен, рекомендуется повторить попытку с экспоненциальной задержкой или переключиться на другую доступную модель GLM (например, временно переключиться с `glm-5.1` на `glm-4.7` или `glm-4.6`).

## Заключение

С помощью этого документа вы узнали, как использовать GLM Chat Completion API для вызова моделей серии GLM от Zhizhu AI, включая основные вызовы, потоковые ответы, многократные диалоги, системные подсказки и вызовы инструментов. Надеемся, что этот документ поможет вам лучше интегрировать и использовать этот API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.


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