> ## 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 Richiesta e Utilizzo

> GLM API guide - Ace Data Cloud

GLM (General Language Model) è una nuova generazione di modelli di linguaggio lanciata da Zhipu AI (Zhipu AI / Z.ai), dotata di potenti capacità di comprensione e generazione in cinese e inglese, con prestazioni eccezionali in scenari cinesi, generazione di codice, inferenza e dialoghi multi-turno. I nuovi modelli di generazione GLM-5.3, GLM-5.2, GLM-4.7, ecc. hanno subito molte ottimizzazioni in contesti lunghi, chiamate a strumenti e compiti di codice, e possono essere ampiamente utilizzati in scenari di domande e risposte intelligenti, creazione di contenuti, assistenza al codice, chatbot di servizio clienti, ecc.

Questo documento descrive principalmente il processo di utilizzo dell'API GLM Chat Completion, che consente di chiamare facilmente i modelli della serie GLM tramite un'interfaccia compatibile con OpenAI.

## Processo di Richiesta

Per utilizzare l'API GLM Chat Completion, prima di tutto vai al [Pannello di Controllo di Ace Data Cloud](https://platform.acedata.cloud/console/applications) per ottenere il tuo API Token, da conservare per uso futuro.

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

Se non hai ancora effettuato il login o la registrazione, verrai automaticamente reindirizzato alla pagina di login che ti invita a registrarti e accedere; una volta completato, verrai riportato automaticamente alla pagina corrente.

**Un API Token è sufficiente per accedere a tutti i servizi della piattaforma, senza necessità di richiederne uno separato per ogni servizio.** La prima richiesta riceverà un credito gratuito, che consente di provare gratuitamente; se il credito è insufficiente, puoi ricaricare il saldo generale nel [pannello di controllo](https://platform.acedata.cloud/console/coin).

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

## Utilizzo di Base

L'indirizzo di richiesta per l'API GLM Chat Completion è `https://api.acedata.cloud/glm/chat/completions`, utilizzando l'autenticazione Bearer Token; il corpo della richiesta è compatibile con il protocollo OpenAI Chat Completions.

Quando utilizzi per la prima volta questa interfaccia, è necessario compilare almeno tre contenuti:

* `authorization`: seleziona direttamente il Bearer Token dal menu a discesa.
* `model`: scegli il modello GLM da chiamare; i modelli attualmente supportati includono:
  * `glm-5.3`: il modello di punta più recente, supporta 1M di contesto e un massimo di 128K di output, adatto per inferenze complesse, codice e compiti di Agent. L'inferenza è sempre attivata e puoi scegliere `reasoning_effort` tra `low`, `high` o `max`.
  * `glm-5.2`: il modello di punta della generazione precedente, con forti capacità complessive.
  * `glm-5.1`: modello di punta maturo, adatto per compiti complessi generali.
  * `glm-4.7`: eccelle in inferenza, chiamate a strumenti e compiti di codice.
  * `glm-4.6`: modello di dialogo generale, bilancia effetti e costi.
  * `glm-3-turbo`: modello di dialogo classico, adatto per compiti generali di generazione di testo.
* `messages`: array di messaggi, ogni messaggio contiene `role` e `content`, `role` supporta tre ruoli: `user`, `assistant`, `system`.

Parametri opzionali comunemente usati:

* `max_tokens`: limita il numero massimo di token per una singola risposta.
* `temperature`: casualità nella generazione, tra 0-2, valori più alti portano a maggiore dispersione.
* `top_p`: parametro di campionamento nucleare, controlla la soglia di probabilità cumulativa dei token candidati.
* `n`: quante risposte candidate generare in una volta.
* `stream`: se abilitare la risposta in streaming, predefinito `false`.
* `stop`: sequenza di arresto personalizzata.

Di seguito è riportato un esempio di chiamata Python più semplice:

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

Dopo la chiamata, scopriamo che il risultato restituito è il seguente:

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

Le principali spiegazioni dei campi restituiti sono le seguenti:

* `id`: ID unico per il compito di dialogo attuale.
* `created`: data di creazione del compito di dialogo attuale (timestamp Unix, in secondi).
* `model`: nome del modello GLM effettivamente chiamato.
* `choices`: elenco delle risposte generate dal modello. `choices[i].message.content` è il testo specifico della risposta del modello, `finish_reason` indica il motivo di fine (`stop`, `length`, `tool_calls`, `content_filter`, ecc.).
* `usage`: statistiche sull'uso dei token per questa richiesta, includendo `prompt_tokens`, `completion_tokens`, `total_tokens`.

## Risposta in Streaming

Questa interfaccia supporta la risposta in streaming (Server-Sent Events), il che è molto utile per l'integrazione con pagine web, consentendo di visualizzare il testo parola per parola.

Se desideri restituire la risposta in streaming, imposta il parametro `stream` nel corpo della richiesta su `true`.

Codice di esempio per la chiamata 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"))
```

L'output appare come segue (estratto):

```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": "Ciao! Come 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": "aiutarti"}, "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]
```

Si può vedere che ci sono molti `data` nella risposta, ogni `data` contiene un frammento incrementale. `choices[i].delta.content` è il frammento di testo aggiunto nel chunk corrente, puoi concatenare questi frammenti per formare una risposta completa. Quando il contenuto di `data` è `[DONE]`, indica che la risposta in streaming è terminata. L'ultimo chunk con `usage` riassumerà l'uso dei token per questa richiesta.

Esempio in 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));
}
```

Esempio di codice 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());
```

Altre lingue possono essere riscritte separatamente, il principio è lo stesso.

## Conversazione multipla

Se desideri implementare una funzionalità di conversazione multipla, devi inserire le conversazioni storiche nell'array `messages`, mantenendo l'ordine alternato tra `user` e `assistant`.

Esempio di chiamata in 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": "Ciao"},
        {"role": "assistant", "content": "Ciao! Come posso assisterti oggi?"},
        {"role": "user", "content": "Cosa ho appena detto?"}
    ]
}

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

Caricando più domande, puoi facilmente realizzare una conversazione multipla e ottenere la seguente risposta:

```json theme={null}
{
  "id": "msg_20260426225208b95324e9945a48d3",
  "model": "glm-4.7",
  "object": "chat.completion",
  "created": 1777215128,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hai detto: **\"Ciao\"** 😊\n\nFammi sapere se hai bisogno di qualcos'altro!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 48,
    "completion_tokens": 37,
    "total_tokens": 85
  }
}
```

Si può vedere che le informazioni contenute in `choices` sono coerenti con l'uso di base, il modello fornisce una risposta basata sulla storia completa della conversazione, supportando così l'interazione contestuale multipla.

## Messaggio di sistema (System Prompt)

Puoi aggiungere un messaggio con `role` di `system` all'inizio di `messages` per vincolare il ruolo, lo stile o il comportamento del modello:

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "system", "content": "Sei un assistente di scrittura esperto in cinese, rispondi con un tono conciso e professionale."},
        {"role": "user", "content": "Per favore, introduci il modello GLM in tre frasi."}
    ]
}
```

## Chiamata a strumenti (Function Calling)

Il modello GLM supporta la chiamata a funzioni compatibile con OpenAI, puoi dichiarare le funzioni chiamabili tramite il parametro `tools`, il modello restituirà informazioni strutturate sulla chiamata della funzione in `choices[i].message.tool_calls` quando necessario.

```python theme={null}
payload = {
    "model": "glm-4.7",
    "messages": [
        {"role": "user", "content": "Com'è il tempo a Pechino oggi?"}
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Controlla il tempo in una città specificata",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string", "description": "Nome della città"}
                    },
                    "required": ["city"]
                }
            }
        }
    ]
}
```

Se il modello decide di chiamare uno strumento, il risultato restituirà `finish_reason` come `tool_calls`, e fornirà il nome della funzione e i parametri in forma di stringa JSON in `message.tool_calls`. Puoi eseguire quella funzione e restituire il risultato come un messaggio con `role` di `tool` al modello, completando così il ciclo di chiamata dello strumento.

## Suggerimenti per la scelta del modello

````
| Modello         | Scenari di utilizzo                               |
| ------------- | -------------------------------------------- |
| `glm-5.3`     | Ultimo flagship, 1M contesto, massimo 128K output, raccomandato per ragionamenti complessi, codice e compiti di Agent |
| `glm-5.2`     | Flagship della generazione precedente, adatto per ragionamenti complessi, codice e compiti di Agent                    |
| `glm-5.1`     | Flagship maturo, adatto per ragionamenti complessi, analisi di documenti lunghi                            |
| `glm-4.7`     | Chiamate a strumenti, generazione di codice, orchestrazione di Agent e altri compiti                        |
| `glm-4.6`     | Scelta equilibrata per dialoghi generali e creazione di contenuti                               |
| `glm-3-turbo` | Compiti di generazione di testo generale, scenari sensibili ai costi                            |

## Gestione degli errori

Quando si chiama l'API, se si verifica un errore, l'API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:

- `400 token_mismatched`: parametri di richiesta mancanti o non validi.
- `400 api_not_implemented`: utilizzo di parametri o modelli non supportati.
- `401 invalid_token`: non autorizzato, Bearer Token mancante o scaduto.
- `429 too_many_requests`: attivazione del limite di frequenza, riprovare più tardi.
- `500 api_error`: errore interno del server o upstream temporaneamente non disponibile.

### Esempio di risposta di errore

```json
{
  "trace_id": "69ea9bcf-c5da-41a3-be97-c80912a08523",
  "error": {
    "code": "api_error",
    "message": "Il servizio è temporaneamente non disponibile, riprovare più tardi."
  }
}
````

Quando viene restituito `api_error` e il messaggio è `Il servizio è temporaneamente non disponibile, riprovare più tardi.`, di solito indica che il servizio GLM upstream è temporaneamente non disponibile, si consiglia di riprovare con un backoff esponenziale o di passare a un altro modello GLM disponibile (ad esempio, passare temporaneamente da `glm-5.1` a `glm-4.7` o `glm-4.6`).

## Conclusione

Attraverso questo documento, hai appreso come utilizzare l'API di completamento chat GLM per chiamare i modelli della serie GLM di Zhiyu AI, inclusi utilizzi tipici come chiamate di base, risposte in streaming, dialoghi multipli, prompt di sistema e chiamate a strumenti. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.


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