> ## 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 dall'SDK Go con c.AI.Chat: chat completion compatibili con OpenAI, senza streaming.

`c.AI.Chat(ctx, 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.

```go theme={"system"}
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

func main() {
	ctx := context.Background()
	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))

	completion, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
		Model: "cubic",
		Messages: []squarecloud.ChatMessage{
			{Role: "system", Content: "You are a helpful assistant."},
			{Role: "user", Content: "What is Square Cloud?"},
		},
		MaxTokens: 512,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
	fmt.Println(completion.Usage.TotalTokens)
}
```

## Richiesta

Campi di `squarecloud.ChatRequest`, con i relativi nomi JSON:

| Campo                                            | Descrizione                                                                                                                                                                                       |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Model` (`model`)                                | `cubic`. Accettato per compatibilità: non esiste un altro modello. `""` non viene inviato                                                                                                         |
| `Messages` (`messages`)                          | `[]ChatMessage` con `Role`, `Content`, `ToolCallID` (`tool_call_id`) e `ToolCalls` (`tool_calls`). `Role` è `system`, `user`, `assistant` o `tool`. `Content` viene sempre inviato, `""` compreso |
| `Tools` / `ToolChoice` (`tools` / `tool_choice`) | Function calling di OpenAI: `Tools` è un `[]json.RawMessage`, `ToolChoice` qualsiasi valore codificabile in JSON                                                                                  |
| `MaxTokens` (`max_tokens`)                       | Numero massimo di token della risposta. `0` non viene inviato                                                                                                                                     |
| `Temperature` (`temperature`)                    | Temperatura di campionamento, un `*float64`. `nil` non viene inviato                                                                                                                              |

La risposta è un `ChatCompletion` con la forma di OpenAI: `ID`, `Object`, `Created`, `Model`, `Choices` (`Index`, `Message`, `FinishReason`) e `Usage` (`PromptTokens`, `CompletionTokens`, `TotalTokens`).

## Niente streaming

`AI.Chat` non usa lo streaming: restituisce l'intera completion. `ChatRequest` non ha un campo `stream`; l'API risponde 400 `stream_not_supported` a `stream: true`.

## Timeout

Il gateway concede a ogni richiesta **90 secondi** in totale, poi risponde 503 `server_overloaded`. Senza una scadenza su `ctx`, l'SDK attende almeno 2 minuti 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**. Vengono comunque restituiti come [`*APIError`](/it/sdks/go/errors), con `Code` impostato sul codice di OpenAI (o sul suo `type` quando non c'è un codice):

```go theme={"system"}
_, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
	Messages: []squarecloud.ChatMessage{{Role: "user", Content: "Hi"}},
})

var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Code == "server_overloaded" {
	// safe to retry yourself
}
```

| 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.