> ## 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 Solicitud y Uso

> GLM API guide - Ace Data Cloud

GLM (Modelo de Lenguaje General) es la nueva generación de modelos de lenguaje lanzada por Zhipu AI (Zhipu AI / Z.ai), que posee una poderosa capacidad de comprensión y generación en chino e inglés, destacándose en tareas como escenarios en chino, generación de código, razonamiento y diálogos de múltiples turnos. Los nuevos modelos de la generación GLM-5.3, GLM-5.2, GLM-4.7, entre otros, han realizado numerosas optimizaciones en contextos largos, llamadas a herramientas y tareas de código, y pueden aplicarse ampliamente en escenarios como preguntas y respuestas inteligentes, creación de contenido, asistencia de código, y chatbots de servicio al cliente.

Este documento describe principalmente el proceso de uso de la API de GLM Chat Completion, que le permite invocar fácilmente los modelos de la serie GLM a través de una interfaz compatible con OpenAI.

## Proceso de Solicitud

Para usar la API de GLM Chat Completion, primero dirígete a la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obtener tu Token de API, que debes guardar como respaldo.

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

Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión; una vez completado, volverás automáticamente a la página actual.

**Un Token de API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio.** La primera solicitud incluirá un crédito gratuito, que te permitirá experimentar sin costo; si el crédito es insuficiente, puedes recargar el saldo general en la [consola](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [GLM Chat Completion API →](https://platform.acedata.cloud/documents/glm-chat-completions)

## Uso Básico

La dirección de solicitud de la API de GLM Chat Completion es `https://api.acedata.cloud/glm/chat/completions`, utilizando autenticación Bearer Token, y el cuerpo de la solicitud es compatible con el protocolo de OpenAI Chat Completions.

En la primera vez que uses esta interfaz, necesitamos completar al menos tres contenidos:

* `authorization`: selecciona directamente Bearer Token en la lista desplegable.
* `model`: elige el modelo GLM que deseas invocar, los modelos actualmente soportados incluyen:
  * `glm-5.3`: el modelo insignia más reciente, soporta 1M de contexto y hasta 128K de salida, adecuado para razonamientos complejos, tareas de código y de Agente. El razonamiento está siempre habilitado, y puedes elegir `reasoning_effort` como `low`, `high` o `max`.
  * `glm-5.2`: modelo insignia de la generación anterior, con fuertes capacidades generales.
  * `glm-5.1`: modelo insignia maduro, adecuado para tareas complejas generales.
  * `glm-4.7`: destaca en razonamiento, llamadas a herramientas y tareas de código.
  * `glm-4.6`: modelo de diálogo general, equilibrando efectividad y costo.
  * `glm-3-turbo`: modelo de diálogo clásico, adecuado para tareas generales de generación de texto.
* `messages`: array de mensajes, cada mensaje incluye `role` y `content`, donde `role` admite tres tipos: `user`, `assistant`, `system`.

Parámetros opcionales comunes:

* `max_tokens`: limita el número máximo de tokens en una sola respuesta.
* `temperature`: aleatoriedad en la generación, entre 0-2, cuanto mayor sea el valor, más dispersa será la respuesta.
* `top_p`: parámetro de muestreo nuclear, controla el umbral de probabilidad acumulativa de los tokens candidatos.
* `n`: cuántas respuestas candidatas generar en una sola vez.
* `stream`: si habilitar o no la respuesta en streaming, por defecto `false`.
* `stop`: secuencia de parada personalizada.

A continuación, se muestra un ejemplo de llamada más simple en 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)
```

Después de la llamada, encontramos que el resultado devuelto es el siguiente:

```json theme={null}
{
  "id": "msg_202604262252030313862701a04e33",
  "model": "glm-5.2",
  "object": "chat.completion",
  "created": 1777215124,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "¡Hola! 👋 ¿Cómo puedo asistirte hoy?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 23,
    "total_tokens": 33
  }
}
```

La explicación de los principales campos del resultado devuelto es la siguiente:

* `id`: ID único de la tarea de diálogo actual.
* `created`: hora de creación de la tarea de diálogo actual (marca de tiempo Unix, en segundos).
* `model`: nombre del modelo GLM realmente invocado.
* `choices`: lista de respuestas generadas por el modelo. `choices[i].message.content` es el texto específico de la respuesta del modelo, `finish_reason` indica la razón de finalización (`stop`, `length`, `tool_calls`, `content_filter`, etc.).
* `usage`: estadísticas del uso de tokens en esta solicitud, que incluye `prompt_tokens`, `completion_tokens`, `total_tokens`.

## Respuesta en Streaming

Esta interfaz soporta respuestas en streaming (Eventos Enviados por el Servidor), lo cual es muy útil para la integración en páginas web, permitiendo mostrar el contenido palabra por palabra.

Si deseas que la respuesta se devuelva en streaming, simplemente establece el parámetro `stream` en `true` en el cuerpo de la solicitud.

Código de ejemplo en Python para la llamada:

```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"))
```

El efecto de salida es el siguiente (extracto):

```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": "¡Hola! ¿En qué puedo"}, "finish_reason": null, "index": 0}], "usage": null}

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

Se puede ver que hay muchos `data` en la respuesta, cada `data` contiene un fragmento incremental. `choices[i].delta.content` es el fragmento de texto nuevo añadido en el chunk actual, puedes concatenar estos fragmentos para formar una respuesta completa. Cuando el contenido de `data` es `[DONE]`, indica que la respuesta en streaming ha terminado. El último chunk que lleva `usage` resumirá el uso de tokens de esta solicitud.

Ejemplo en 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));
}
```

Ejemplo de código en 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());
```

Otros lenguajes pueden ser reescritos de manera similar, el principio es el mismo.

## Diálogo en múltiples turnos

Si deseas implementar la función de diálogo en múltiples turnos, necesitas colocar el historial de conversación en el arreglo `messages`, manteniendo el orden alternado de `user` y `assistant`.

Ejemplo de código en 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": "Hola"},
        {"role": "assistant", "content": "¡Hola! ¿Cómo puedo asistirte hoy?"},
        {"role": "user", "content": "¿Qué dije justo ahora?"}
    ]
}

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

Al subir múltiples preguntas, puedes lograr fácilmente un diálogo en múltiples turnos, obteniendo respuestas como la siguiente:

```json theme={null}
{
  "id": "msg_20260426225208b95324e9945a48d3",
  "model": "glm-4.7",
  "object": "chat.completion",
  "created": 1777215128,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Dijiste: **\"Hola\"** 😊\n\n¡Déjame saber si necesitas algo más!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 37,
    "total_tokens": 85
  }
}
```

Se puede ver que la información en `choices` es consistente con el uso básico, el modelo proporciona una respuesta basada en el historial completo de la conversación, lo que permite la interacción contextual en múltiples turnos.

## Mensaje de sistema (System Prompt)

Puedes agregar un mensaje con `role` de `system` al principio de `messages` para restringir el rol, estilo o comportamiento del modelo:

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "system", "content": "Eres un asistente de escritura en chino experimentado, por favor responde con un tono conciso y profesional."},
        {"role": "user", "content": "Por favor, presenta el modelo GLM en tres oraciones."}
    ]
}
```

## Llamada a funciones (Function Calling)

El modelo GLM soporta llamadas a funciones compatibles con OpenAI, puedes declarar funciones llamables a través del parámetro `tools`, el modelo devolverá información estructurada de la llamada a la función en `choices[i].message.tool_calls` cuando sea necesario.

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "user", "content": "¿Cómo está el clima en Beijing hoy?"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Consulta el clima de una ciudad específica",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "Nombre de la ciudad"}
                    },
                    "required": ["city"]
                }
            }
        }
    ]
}
```

Si el modelo decide llamar a una herramienta, el resultado tendrá `finish_reason` cambiado a `tool_calls`, y en `message.tool_calls` se proporcionará el nombre de la función y los parámetros en forma de cadena JSON. Puedes ejecutar esa función y devolver el resultado como un mensaje con `role` de `tool` al modelo, completando así el ciclo de llamada a la herramienta.

## Sugerencias para la selección de modelos

````
| Modelo          | Escenario aplicable                               |
| --------------- | ------------------------------------------------- |
| `glm-5.3`      | Última insignia, contexto de 1M, salida máxima de 128K, recomendado para razonamiento complejo, tareas de código y agentes |
| `glm-5.2`      | Insignia de la generación anterior, adecuada para razonamiento complejo, tareas de código y agentes |
| `glm-5.1`      | Insignia madura, adecuada para razonamiento complejo, análisis de documentos largos |
| `glm-4.7`      | Llamadas a herramientas, generación de código, orquestación de agentes y otras tareas |
| `glm-4.6`      | Opción equilibrada para diálogos generales y creación de contenido |
| `glm-3-turbo`  | Tareas generales de generación de texto, escenarios sensibles al costo |

## Manejo de errores

Al llamar a la API, si se encuentra un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:

- `400 token_mismatched`: Parámetros de solicitud faltantes o inválidos.
- `400 api_not_implemented`: Se utilizaron parámetros o modelos no soportados.
- `401 invalid_token`: No autorizado, falta o ha expirado el Bearer Token.
- `429 too_many_requests`: Se ha activado el límite de frecuencia, por favor intente de nuevo más tarde.
- `500 api_error`: Error interno del servidor o el servicio model service está temporalmente no disponible.

### Ejemplo de respuesta de error

```json
{
  "trace_id": "69ea9bcf-c5da-41a3-be97-c80912a08523",
  "error": {
    "code": "api_error",
    "message": "El servicio está temporalmente no disponible, por favor intente de nuevo más tarde."
  }
}
````

Cuando se devuelve `api_error` y el mensaje es `El servicio está temporalmente no disponible, por favor intente de nuevo más tarde.`, generalmente indica que el servicio GLM upstream está temporalmente no disponible, se sugiere reintentar con retroceso exponencial, o cambiar a otro modelo GLM disponible (por ejemplo, cambiar temporalmente de `glm-5.1` a `glm-4.7` o `glm-4.6`).

## Conclusión

A través de este documento, ha aprendido cómo utilizar la API de GLM Chat Completion para llamar a los modelos de la serie GLM de Zhiyu AI, incluyendo llamadas básicas, respuestas en streaming, diálogos de múltiples turnos, mensajes del sistema y llamadas a herramientas, entre otros usos típicos. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en contactar a nuestro equipo de soporte técnico.


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