AI Gateway compatible OpenAI (bêta)

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

string

requis

La clé d’API de votre compte. Vous pouvez la trouver dans les paramètres de votre compte.

Nécessite une clé API avec le scope 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). 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

string

Accepté pour la compatibilité avec les SDK ; la gateway répond toujours en tant que cubic.

array

requis

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.

number

Ramené silencieusement au plafond de sortie de votre plan.

number

De 0 à 2.

array

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

string | object

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

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);

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)

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." }
    ]
  }'

{
  "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

Garde-t-elle en mémoire les conversations ?

Non, l’API est sans état, exactement comme celle d’OpenAI : envoyez l’historique de la conversation dans messages à chaque requête.

De quel modèle s'agit-il ?

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.

Puis-je l'appeler depuis une application hébergée sur Square Cloud ?

Oui, c’est le cas d’usage principal. C’est une API HTTPS classique, elle fonctionne donc depuis n’importe où.

L'usage de la gateway affecte-t-il mon assistant IA du tableau de bord ?

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() (JavaScript), client.ai.chat() (Python), c.AI.Chat() (Go)

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

Premiers pas

Compte

Applications

Bases de données

Workspaces

IA

AI Gateway compatible OpenAI (bêta)

Comment se connecter

Plans et limites

Contrat de la requête

Recherche web intégrée

Erreurs

Questions fréquentes

Voir aussi

​Comment se connecter

​Plans et limites

​Contrat de la requête

​Recherche web intégrée

​Erreurs

​Questions fréquentes

​Voir aussi

Comment se connecter

Plans et limites

Contrat de la requête

Recherche web intégrée

Erreurs

Questions fréquentes

Voir aussi