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

# IA

> Appelez l'AI Gateway de Square Cloud depuis le SDK Go avec c.AI.Chat : des chat completions compatibles OpenAI, sans streaming.

`c.AI.Chat(ctx, request)` appelle l'[AI Gateway](/en/api-reference/ai-gateway), un endpoint de chat completions **compatible OpenAI**. Il nécessite le scope `ai:chat` et un plan Standard ou supérieur.

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

## Requête

Champs de `squarecloud.ChatRequest`, avec leurs noms JSON :

| Champ                                            | Description                                                                                                                                                                                           |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Model` (`model`)                                | `cubic`. Accepté pour la compatibilité : il n'y a pas d'autre modèle. `""` n'est pas envoyé                                                                                                           |
| `Messages` (`messages`)                          | `[]ChatMessage` avec `Role`, `Content`, `ToolCallID` (`tool_call_id`) et `ToolCalls` (`tool_calls`). `Role` vaut `system`, `user`, `assistant` ou `tool`. `Content` est toujours envoyé, `""` compris |
| `Tools` / `ToolChoice` (`tools` / `tool_choice`) | Function calling d'OpenAI : `Tools` est un `[]json.RawMessage`, `ToolChoice` toute valeur encodable en JSON                                                                                           |
| `MaxTokens` (`max_tokens`)                       | Nombre maximal de tokens de la réponse. `0` n'est pas envoyé                                                                                                                                          |
| `Temperature` (`temperature`)                    | Température d'échantillonnage, un `*float64`. `nil` n'est pas envoyé                                                                                                                                  |

La réponse est un `ChatCompletion` de forme OpenAI : `ID`, `Object`, `Created`, `Model`, `Choices` (`Index`, `Message`, `FinishReason`) et `Usage` (`PromptTokens`, `CompletionTokens`, `TotalTokens`).

## Pas de streaming

`AI.Chat` ne diffuse pas en flux : elle renvoie la completion entière. `ChatRequest` n'a pas de champ `stream` ; l'API répond 400 `stream_not_supported` à `stream: true`.

## Timeout

La gateway accorde à chaque requête **90 secondes** au total, puis répond 503 `server_overloaded`. Sans échéance sur `ctx`, le SDK attend au moins 2 minutes avant d'expirer, vous recevez donc la réponse de la gateway.

## Erreurs

Les erreurs d'IA utilisent le format OpenAI, leurs codes sont donc en **minuscules**. Elles sont tout de même renvoyées sous forme d'une [`*APIError`](/fr/sdks/go/errors), avec `Code` défini sur le code OpenAI (ou sur son `type` en l'absence de code) :

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

| Statut | Code                                                                                                    | Quand                                                                                      |
| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 400    | `stream_not_supported`                                                                                  | `stream: true` a été envoyé                                                                |
| 400    | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | Un champ mal formé                                                                         |
| 400    | `context_length_exceeded`                                                                               | La conversation dépasse la fenêtre de contexte du plan                                     |
| 401    | `access_denied`                                                                                         | Clé API invalide                                                                           |
| 403    | `upgrade_required`                                                                                      | Le plan n'a pas accès à l'AI Gateway                                                       |
| 429    | `rate_limit_exceeded`, `concurrent_limit_reached`                                                       | Trop rapide, ou une requête déjà en cours                                                  |
| 429    | `daily_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached`                       | Un budget quotidien est épuisé (réinitialisé à 00:00 UTC)                                  |
| 503    | `server_overloaded`                                                                                     | La capacité est pleine ou le délai de 90 s est dépassé : vous pouvez réessayer sans risque |
| 503    | `daily_capacity_reached`                                                                                | La capacité quotidienne de la plateforme est épuisée                                       |

Le SDK **ne réessaie jamais** les erreurs d'IA : la requête est un `POST` non idempotent. Consultez la [référence de l'AI Gateway](/en/api-reference/ai-gateway) pour les limites des plans.