> ## 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 Solicitação e Uso

> GLM API guide - Ace Data Cloud

GLM (General Language Model) é uma nova geração da série de modelos de linguagem desenvolvida pela Zhipu AI (Zhipu AI / Z.ai), que possui uma forte capacidade de compreensão e geração em chinês e inglês, apresentando um desempenho excepcional em tarefas como cenários em chinês, geração de código, raciocínio e diálogos de múltiplas rodadas. Modelos de nova geração como GLM-5.3, GLM-5.2, GLM-4.7, entre outros, foram amplamente otimizados para contextos longos, chamadas de ferramentas e tarefas de código, podendo ser amplamente aplicados em cenários como perguntas e respostas inteligentes, criação de conteúdo, assistência de código, robôs de atendimento ao cliente, entre outros.

Este documento apresenta principalmente o processo de uso da API GLM Chat Completion, permitindo que você chame facilmente os modelos da série GLM através de uma interface compatível com OpenAI.

## Processo de Solicitação

Para usar a API GLM Chat Completion, primeiro acesse o [console da Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu Token de API, que deve ser guardado para uso futuro.

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

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login. Após a conclusão, você será redirecionado de volta para a página atual.

**Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço.** A primeira solicitação oferece um crédito gratuito, permitindo uma experiência sem custo; quando o crédito estiver baixo, você pode recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentação Completa: [GLM Chat Completion API →](https://platform.acedata.cloud/documents/glm-chat-completions)

## Uso Básico

O endereço de solicitação da API GLM Chat Completion é `https://api.acedata.cloud/glm/chat/completions`, utilizando autenticação Bearer Token, e o corpo da solicitação é compatível com o protocolo OpenAI Chat Completions.

Na primeira utilização dessa interface, precisamos preencher pelo menos três conteúdos:

* `authorization`: selecione diretamente o Bearer Token na lista suspensa.
* `model`: escolha o modelo GLM a ser chamado, atualmente os modelos suportados incluem:
  * `glm-5.3`: modelo mais recente e de ponta, suporta 1M de contexto e até 128K de saída, adequado para raciocínio complexo, tarefas de código e de agente. O raciocínio está sempre ativado, podendo ser selecionado através de `reasoning_effort` como `low`, `high` ou `max`.
  * `glm-5.2`: modelo de ponta da geração anterior, com forte capacidade geral.
  * `glm-5.1`: modelo de ponta maduro, adequado para tarefas complexas gerais.
  * `glm-4.7`: apresenta excelente desempenho em raciocínio, chamadas de ferramentas e tarefas de código.
  * `glm-4.6`: modelo de diálogo geral, equilibrando eficácia e custo.
  * `glm-3-turbo`: modelo de diálogo clássico, adequado para tarefas gerais de geração de texto.
* `messages`: array de mensagens, cada mensagem contém `role` e `content`, onde `role` suporta três tipos: `user`, `assistant`, `system`.

Parâmetros opcionais comuns:

* `max_tokens`: limita o número máximo de tokens na resposta única.
* `temperature`: aleatoriedade na geração, entre 0-2, quanto maior o valor, mais disperso.
* `top_p`: parâmetro de amostragem nuclear, controla o limite de probabilidade acumulada dos tokens candidatos.
* `n`: quantas respostas candidatas gerar de uma vez.
* `stream`: se habilitar a resposta em fluxo, padrão `false`.
* `stop`: sequência de parada personalizada.

Abaixo está um exemplo mais simples de chamada em 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)
```

Após a chamada, encontramos o resultado retornado como segue:

```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
  }
}
```

Abaixo estão as principais explicações dos campos retornados:

* `id`: ID único da tarefa de diálogo atual.
* `created`: hora de criação da tarefa de diálogo atual (timestamp Unix, em segundos).
* `model`: nome do modelo GLM realmente chamado.
* `choices`: lista de respostas geradas pelo modelo. `choices[i].message.content` é o texto específico da resposta do modelo, e `finish_reason` indica a razão do término (`stop`, `length`, `tool_calls`, `content_filter`, etc.).
* `usage`: estatísticas de uso de tokens para esta solicitação, incluindo `prompt_tokens`, `completion_tokens`, `total_tokens`.

## Resposta em Fluxo

Esta interface suporta resposta em fluxo (Server-Sent Events), o que é muito útil para integração em páginas da web, permitindo que a página exiba o efeito de exibição palavra por palavra.

Se você deseja retornar a resposta em fluxo, basta definir o parâmetro `stream` no corpo da solicitação como `true`.

Código de exemplo de chamada em 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"))
```

O efeito de saída é como segue (trecho):

```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": "Olá! Como posso"}, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "ajudar você"}, "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]
```

Pode-se ver que a resposta contém muitos `data`, cada `data` inclui um fragmento incremental. `choices[i].delta.content` é o fragmento de texto adicionado atualmente, você pode concatenar esses fragmentos para formar uma resposta completa. Quando o conteúdo de `data` é `[DONE]`, isso indica que a resposta em fluxo terminou. O último fragmento com `usage` resumirá o uso de tokens desta solicitação.

Exemplo em 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: "oi" }],
    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));
}
```

Exemplo de código em 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", "oi")));
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());
```

Outras linguagens podem ser reescritas de forma semelhante, o princípio é o mesmo.

## Diálogo em várias rodadas

Se você deseja implementar a funcionalidade de diálogo em várias rodadas, deve colocar o histórico de conversas no array `messages`, mantendo a ordem alternada entre `user` e `assistant`.

Exemplo de código em 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": "Olá"},
        {"role": "assistant", "content": "Oi! Como posso ajudar você hoje?"},
        {"role": "user", "content": "O que eu disse agora há pouco?"}
    ]
}

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

Ao enviar várias perguntas, você pode facilmente realizar diálogos em várias rodadas e obter a seguinte resposta:

```json theme={null}
{
  "id": "msg_20260426225208b95324e9945a48d3",
  "model": "glm-4.7",
  "object": "chat.completion",
  "created": 1777215128,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Você disse: **\"Olá\"** 😊\n\nDeixe-me saber se você precisa de mais alguma coisa!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 37,
    "total_tokens": 85
  }
}
```

Pode-se ver que as informações contidas em `choices` são consistentes com o uso básico, o modelo fornece uma resposta com base no histórico completo da conversa, suportando assim a interação contextual em várias rodadas.

## Mensagem de sistema (System Prompt)

Você pode adicionar uma mensagem com `role` como `system` no início de `messages` para restringir o papel, estilo ou comportamento do modelo:

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "system", "content": "Você é um assistente de escrita em chinês experiente, por favor, responda de forma concisa e profissional."},
        {"role": "user", "content": "Por favor, apresente o modelo GLM em três frases."}
    ]
}
```

## Chamada de função (Function Calling)

O modelo GLM suporta chamadas de função compatíveis com OpenAI, você pode declarar funções chamáveis através do parâmetro `tools`, o modelo retornará informações estruturadas de chamada de função em `choices[i].message.tool_calls` quando necessário.

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "user", "content": "Como está o tempo em Pequim hoje?"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Consultar o tempo em uma cidade específica",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "Nome da cidade"}
                    },
                    "required": ["city"]
                }
            }
        }
    ]
}
```

Se o modelo decidir chamar a ferramenta, o resultado retornado terá `finish_reason` alterado para `tool_calls`, e fornecerá o nome da função e os parâmetros em forma de string JSON em `message.tool_calls`. Você pode executar essa função e retornar o resultado como uma mensagem com `role` como `tool` para o modelo, completando assim o ciclo de chamada de ferramenta.

## Sugestões de escolha de modelo

| Modelo | Cenários aplicáveis |
| - | - |
| `glm-5.3` | Última geração, contexto de 1M, saída máxima de 128K, recomendado para raciocínio complexo, tarefas de código e Agent |
| `glm-5.2` | Geração anterior, adequado para raciocínio complexo, tarefas de código e Agent |
| `glm-5.1` | Modelo maduro, adequado para raciocínio complexo, análise de documentos longos |
| `glm-4.7` | Chamadas de ferramentas, geração de código, orquestração de Agent e outras tarefas |
| `glm-4.6` | Escolha equilibrada para diálogos gerais e criação de conteúdo |
| `glm-3-turbo` | Tarefas gerais de geração de texto, cenários sensíveis a custos |

## Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o código de erro e a mensagem correspondente. Por exemplo:

* `400 token_mismatched`: Parâmetros de solicitação ausentes ou inválidos.
* `400 api_not_implemented`: Parâmetros ou modelos não suportados foram utilizados.
* `401 invalid_token`: Não autorizado, Bearer Token ausente ou inválido.
* `429 too_many_requests`: Limite de frequência acionado, por favor, tente novamente mais tarde.
* `500 api_error`: Erro interno do servidor ou upstream temporariamente indisponível.

### Exemplo de Resposta de Erro

```json theme={null}
{
  "trace_id": "69ea9bcf-c5da-41a3-be97-c80912a08523",
  "error": {
    "code": "api_error",
    "message": "Serviço temporariamente indisponível, por favor, tente novamente mais tarde."
  }
}
```

Quando retornar `api_error` e a mensagem for `Serviço temporariamente indisponível, por favor, tente novamente mais tarde.`, geralmente indica que o serviço GLM upstream está temporariamente indisponível, recomenda-se tentar novamente com um backoff exponencial ou mudar para outro modelo GLM disponível (por exemplo, mudar temporariamente de `glm-5.1` para `glm-4.7` ou `glm-4.6`).

## Conclusão

Através deste documento, você já entendeu como usar a API de Conclusão de Chat GLM para chamar os modelos da série GLM da Zhiyu AI, incluindo chamadas básicas, respostas em fluxo, diálogos de múltiplas rodadas, prompts de sistema e chamadas de ferramentas, entre outros usos típicos. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.


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