> ## 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 Gateway compatible OpenAI (bêta)
> Utilisez le modèle cubic de Square Cloud dans vos produits via POST /v2/ai/chat/completions, compatible OpenAI, avec tool calling et recherche web.
La clé d'API de votre compte. Vous pouvez la trouver dans les [paramètres de votre compte](https://squarecloud.app/fr/account/security).
Nécessite une clé API avec le [scope](/fr/api-reference/authentication#scopes) `ai:chat`.
L'AI Gateway vous permet d'utiliser le modèle d'IA hébergé par Square Cloud dans vos **propres** produits (chatbots, assistants, automatisations) via un endpoint de chat completions **compatible OpenAI**. Si votre code parle déjà l'API OpenAI, il parle aussi l'AI Gateway : pointez le SDK vers notre URL de base, utilisez la clé API de votre compte et définissez le modèle sur `cubic`.
L'AI Gateway est en **bêta avec accès anticipé gratuit** : pendant la bêta, aucun frais ne s'ajoute au budget quotidien de tokens d'IA de votre plan. Les limites et les plans concernés peuvent changer à la fin de la bêta.
## Comment se connecter
* **URL de base :** `https://api.squarecloud.app/v2/ai`
* **Clé API :** la clé API de votre compte (la même que celle utilisée par l'API et la CLI Square Cloud, disponible sur la [page du compte](https://squarecloud.app/fr/account)). L'en-tête `Authorization` est accepté avec ou sans le préfixe `Bearer `.
* **Modèle :** `cubic`, le modèle hébergé par Square Cloud, le même que celui qui alimente l'assistant IA du tableau de bord.
## Plans et limites
Chaque requête décompte ses tokens réels du **budget quotidien de tokens d'IA** de votre plan (le même budget que celui de l'assistant du tableau de bord, réinitialisé à 00:00 UTC). Les plans Standard et Pro ont aussi un plafond quotidien de requêtes, et chaque plan dispose d'une allocation quotidienne d'usage raisonnable sur la gateway, dimensionnée pour un usage modéré (un garde-fou contre les clés laissées sans surveillance, basé sur le coût réel des requêtes) ; les deux sont réinitialisés au même moment.
| Plan | Requêtes par jour | Allocation d'usage raisonnable | Fenêtre de contexte | Sortie max. | Requêtes simultanées | Intervalle entre requêtes |
| - | - | - | - | - | - | - |
| Standard | 1 000 | base | 16 384 tokens | 4 096 | 1 | 5 s |
| Pro | 5 000 | base | 24 576 tokens | 6 144 | 1 | 2 s |
| Enterprise | illimitées | 5x la base | 32 768 tokens | 8 192 | 2 | aucun |
Les plans Hobby (et les comptes sans plan) n'ont pas accès à l'AI Gateway : passer au plan Standard ou supérieur l'active.
## Contrat de la requête
Accepté pour la compatibilité avec les SDK ; la gateway répond toujours en tant que `cubic`.
Messages au format OpenAI avec les rôles `system`, `user`, `assistant` et `tool`. Le contenu doit être une **chaîne** : cet endpoint est uniquement textuel, donc un tableau multi-parties (`image_url`, `input_audio`, `file`) est rejeté avec `400 multimodal_not_supported`. Jusqu'à **100 messages** par requête.
Ramené silencieusement au plafond de sortie de votre plan.
De 0 à 2.
Appel de fonctions au format OpenAI standard, jusqu'à **32 définitions d'outils**. Les appels d'outils reviennent avec `finish_reason: "tool_calls"`, et vous renvoyez les résultats sous forme de messages `role: "tool"`.
Valeurs `tool_choice` standard d'OpenAI.
Les paramètres inconnus sont ignorés, avec deux exceptions délibérées : `audio` et une valeur de `modalities` autre que `["text"]` sont **rejetés** plutôt qu'ignorés, afin qu'une demande de sortie vocale ne revienne jamais sous forme de texte muet.
**Texte en entrée, texte en sortie.** Les images, l'audio et les fichiers ne sont acceptés sur aucun plan, et c'est une décision produit plutôt qu'une lacune temporaire. Envoyez du texte et lisez du texte en retour.
**Pas encore pris en charge :** le streaming (`stream: true` renvoie `400 stream_not_supported`).
### Recherche web intégrée
Le modèle décide seul de chercher sur le web lorsque la conversation demande des informations actuelles ou externes. Les recherches s'exécutent côté serveur, et seule la réponse finale est renvoyée, en citant les URL des résultats. Si vous déclarez votre propre outil nommé `web_search`, il remplace l'outil intégré.
```javascript JavaScript (OpenAI SDK) theme={"system"}
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.squarecloud.app/v2/ai",
apiKey: process.env.SQUARECLOUD_API_KEY,
});
const completion = await client.chat.completions.create({
model: "cubic",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Explain what Square Cloud is in one sentence." },
],
});
console.log(completion.choices[0].message.content);
```
```python Python (OpenAI SDK) theme={"system"}
from openai import OpenAI
client = OpenAI(
base_url="https://api.squarecloud.app/v2/ai",
api_key="YOUR_API_KEY",
)
completion = client.chat.completions.create(
model="cubic",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain what Square Cloud is in one sentence."},
],
)
print(completion.choices[0].message.content)
```
```bash cURL theme={"system"}
curl --request POST \
--url https://api.squarecloud.app/v2/ai/chat/completions \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "cubic",
"messages": [
{ "role": "user", "content": "Explain what Square Cloud is in one sentence." }
]
}'
```
```json theme={"system"}
{
"id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
"object": "chat.completion",
"created": 1754179200,
"model": "cubic",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Square Cloud is a cloud platform that hosts your applications, bots, websites and databases with zero infrastructure setup."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 24,
"total_tokens": 52
}
}
```
## Erreurs
Chaque erreur utilise le format OpenAI `{ "error": { "message", "type", "param", "code" } }`, y compris les erreurs d'authentification, de scope, de limite de débit, de corps invalide, `500` et `503`, et le `code` est toujours en minuscules.
| Statut | Code | Signification / que faire |
| - | - | - |
| 401 | `access_denied` | La clé API est manquante, invalide, révoquée ou expirée. |
| 403 | `upgrade_required` | Le plan n'a pas accès à l'AI Gateway (Hobby ou sans plan). Passez au plan Standard ou supérieur. |
| 403 | `missing_scope` | La clé API n'a pas le scope requis par cet endpoint. |
| 403 | `resource_not_allowed` | La clé API est restreinte à des ressources qui ne couvrent pas cette requête. |
| 400 | `invalid_json_body` / `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | Corps de requête mal formé : corrigez le champ signalé. |
| 400 | `stream_not_supported` | Retirez `stream: true` ; le streaming n'est pas encore disponible. |
| 400 | `multimodal_not_supported` | L'endpoint est uniquement textuel. Envoyez le `content` de chaque message sous forme de chaîne, et retirez `audio` ou toute valeur de `modalities` au-delà de `["text"]`. |
| 400 | `context_length_exceeded` | Les messages et les définitions d'outils dépassent la fenêtre de contexte du plan. Raccourcissez l'historique ou changez de plan. |
| 400 | `invalid_request` | Le backend du modèle a refusé la requête : presque toujours une erreur de protocole d'appel d'outils (un message `tool` qui ne répond à aucun `tool_calls` précédent, des ids d'appel en double). |
| 413 | `payload_too_large` | Le corps de la requête dépasse ce que cet endpoint accepte. Raccourcissez l'historique. |
| 429 | `concurrent_limit_reached` | Une requête est déjà en cours ; attendez qu'elle se termine (Enterprise en autorise 2 à la fois). |
| 429 | `rate_limit_exceeded` | Requêtes envoyées plus vite que l'intervalle du plan ; ajoutez le délai côté client. |
| 429 | `daily_request_limit_reached` | Le plafond quotidien de requêtes du plan est atteint (Standard 1 000 / Pro 5 000) ; il est réinitialisé à 00:00 UTC. Enterprise n'a pas de plafond. |
| 429 | `daily_spend_limit_reached` | L'allocation quotidienne d'usage raisonnable du plan sur la gateway est atteinte ; elle est réinitialisée à 00:00 UTC. Enterprise dispose de 5x l'allocation de base. |
| 429 | `daily_limit_reached` | Le budget quotidien de tokens d'IA est épuisé ; il est réinitialisé à 00:00 UTC. Un changement de plan augmente le budget. |
| 429 | `rate_limited` | La limite de requêtes du compte ou de la clé API a été atteinte ; patientez puis réessayez. |
| 500 | `internal_server_error` | Échec inattendu. Réessayez. |
| 503 | `server_overloaded` | La capacité est momentanément saturée, ou la requête a dépassé le délai total de 90 secondes ; réessayez sous peu (les SDK OpenAI réessaient automatiquement). |
| 503 | `daily_capacity_reached` | La capacité quotidienne partagée de l'AI Gateway, pour toute la plateforme, est épuisée. Elle est réinitialisée à 00:00 UTC ; réessayer avant ne sert à rien. |
| 503 | `database_unavailable` | La plateforme est brièvement indisponible. Réessayez dans quelques secondes. |
Trois de ces codes se ressemblent mais n'ont pas le même sens :
* `429 daily_spend_limit_reached` : la limite quotidienne de **votre** clé, fixée par votre plan.
* `503 daily_capacity_reached` : la capacité quotidienne de la **plateforme** pour la gateway, partagée par tous les clients.
* `503 server_overloaded` : une surcharge momentanée, ou une requête qui a pris plus de 90 secondes au total (file d'attente du fournisseur, nouvelles tentatives et recherches comprises). Réessayez dans quelques secondes.
## Questions fréquentes
Non, l'API est sans état, exactement comme celle d'OpenAI : envoyez l'historique de la conversation dans `messages` à chaque requête.
`cubic`, le modèle hébergé par Square Cloud. Il n'y a pas de liste de modèles parmi lesquels choisir ; le champ `model` est accepté pour la compatibilité avec les SDK.
Oui, c'est le cas d'usage principal. C'est une API HTTPS classique, elle fonctionne donc depuis n'importe où.
Oui : les deux consomment le même budget quotidien de tokens d'IA, donc un usage intensif de la gateway réduit le budget disponible pour l'assistant du tableau de bord, et inversement.
## Voir aussi
* SDK : [`api.ai.chat()`](/fr/sdks/js/ai) (JavaScript), [`client.ai.chat()`](/fr/sdks/py/ai) (Python), [`c.AI.Chat()`](/fr/sdks/go/ai) (Go)