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

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

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

console.log(completion.choices[0].message.content);
console.log(completion.usage.total_tokens);
```

## Requête

| 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/js/errors), avec `code` défini sur le code OpenAI (ou sur son `type` en l'absence de code) :

```typescript theme={"system"}
import { SquareCloudAPIError } from "@squarecloud/api";

try {
    await api.ai.chat({ messages: [{ role: "user", content: "Hi" }] });
} catch (error) {
    if (error instanceof SquareCloudAPIError && error.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.