> ## 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 squarecloud-api avec client.ai.chat() : des chat completions compatibles OpenAI, sans streaming.

`client.ai.chat(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.

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

## Requête

`request` est un dict envoyé tel quel comme corps, de sorte que tout autre paramètre OpenAI est transmis. Il est typé `squarecloud.types.ChatRequest`.

| Champ                   | Description                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `model`                 | `cubic`. Accepté pour la compatibilité : il n'y a pas d'autre modèle                                         |
| `messages`              | `{ role, content?, tool_call_id?, tool_calls? }`, avec `role` valant `system`, `user`, `assistant` ou `tool` |
| `tools` / `tool_choice` | Function calling d'OpenAI                                                                                    |
| `max_tokens`            | Nombre maximal de tokens de la réponse                                                                       |
| `temperature`           | Température d'échantillonnage                                                                                |

La réponse a la forme OpenAI : `id`, `object`, `created`, `model`, `choices` (`index`, `message`, `finish_reason`) et `usage`.

## Pas de streaming

`ai.chat()` ne diffuse pas en flux : elle renvoie la completion entière. `"stream": True` donne 400 `stream_not_supported`.

## Timeout

La gateway accorde à chaque requête **90 secondes** au total, puis répond 503 `server_overloaded`. Le SDK attend au moins 120 s 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 lèvent tout de même une [`SquareCloudAPIError`](/fr/sdks/py/errors), avec `code` défini sur le code OpenAI (ou sur son `type` en l'absence de code) :

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

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