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

# AI

> Chiama l'AI Gateway di Square Cloud da squarecloud-api con client.ai.chat(): chat completion compatibili con OpenAI, senza streaming.

`client.ai.chat(request)` chiama l'[AI Gateway](/en/api-reference/ai-gateway), un endpoint di chat completion **compatibile con OpenAI**. Richiede lo scope `ai:chat` e un piano Standard o superiore.

```python theme={"system"}
completion = client.ai.chat({
    "model": "cubic",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Square Cloud?"},
    ],
    "max_tokens": 512,
})

print(completion["choices"][0]["message"]["content"])
print(completion["usage"]["total_tokens"])
```

## Richiesta

`request` è un dict inviato come body così com'è, quindi qualsiasi altro parametro di OpenAI viene inoltrato. È tipizzato come `squarecloud.types.ChatRequest`.

| Campo                   | Descrizione                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `model`                 | `cubic`. Accettato per compatibilità: non esiste un altro modello                                   |
| `messages`              | `{ role, content?, tool_call_id?, tool_calls? }`, con `role` `system`, `user`, `assistant` o `tool` |
| `tools` / `tool_choice` | Function calling di OpenAI                                                                          |
| `max_tokens`            | Numero massimo di token della risposta                                                              |
| `temperature`           | Temperatura di campionamento                                                                        |

La risposta ha la forma di OpenAI: `id`, `object`, `created`, `model`, `choices` (`index`, `message`, `finish_reason`) e `usage`.

## Niente streaming

`ai.chat()` non effettua streaming: restituisce l'intera completion. `"stream": True` produce 400 `stream_not_supported`.

## Timeout

Il gateway concede a ogni richiesta **90 secondi** in totale, poi risponde 503 `server_overloaded`. L'SDK attende almeno 120 s prima di andare in timeout, così ricevi la risposta del gateway.

## Errori

Gli errori dell'AI usano il formato di OpenAI, quindi i loro codici sono in **minuscolo**. Sollevano comunque un [`SquareCloudAPIError`](/it/sdks/py/errors), con `code` impostato sul codice di OpenAI (o sul suo `type` quando non c'è un codice):

```python theme={"system"}
from squarecloud import SquareCloudAPIError

try:
    client.ai.chat({"messages": [{"role": "user", "content": "Hi"}]})
except SquareCloudAPIError as error:
    if error.code == "server_overloaded":
        ...  # safe to retry yourself
    else:
        raise
```

| Status | Codice                                                                                                  | Quando                                                                   |
| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 400    | `stream_not_supported`                                                                                  | È stato inviato `stream: true`                                           |
| 400    | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | Un campo malformato                                                      |
| 400    | `context_length_exceeded`                                                                               | La conversazione supera la finestra di contesto del piano                |
| 401    | `access_denied`                                                                                         | Chiave API non valida                                                    |
| 403    | `upgrade_required`                                                                                      | Il piano non ha accesso all'AI Gateway                                   |
| 429    | `rate_limit_exceeded`, `concurrent_limit_reached`                                                       | Troppo veloce, o una richiesta già in corso                              |
| 429    | `daily_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached`                       | Un budget giornaliero è esaurito (si azzera alle 00:00 UTC)              |
| 503    | `server_overloaded`                                                                                     | Capacità piena o superato il limite di 90 s: puoi riprovare in sicurezza |
| 503    | `daily_capacity_reached`                                                                                | La capacità giornaliera della piattaforma è esaurita                     |

L'SDK **non ripete mai** gli errori dell'AI: la richiesta è un `POST` non idempotente. Vedi il [riferimento dell'AI Gateway](/en/api-reference/ai-gateway) per i limiti dei piani.