> ## 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 compatibile con OpenAI (Beta)
> Usa il modello cubic ospitato da Square Cloud nei tuoi prodotti con POST /v2/ai/chat/completions, compatibile con OpenAI, con tool calling e ricerca web.
La chiave API del tuo account. Puoi trovarla nelle [impostazioni del tuo account](https://squarecloud.app/it/account/security).
Richiede una chiave API con lo [scope](/it/api-reference/authentication#scope) `ai:chat`.
L'AI Gateway ti permette di usare il modello AI ospitato da Square Cloud all'interno dei tuoi **prodotti** (chatbot, assistenti, automazioni) tramite un endpoint di chat completions **compatibile con OpenAI**. Se il tuo codice parla già l'API di OpenAI, parla anche l'AI Gateway: punta l'SDK al nostro URL base, usa la chiave API del tuo account e imposta il modello su `cubic`.
L'AI Gateway è in **beta con accesso anticipato gratuito**: durante la beta non ci sono costi aggiuntivi oltre al budget giornaliero di token AI del tuo piano. Limiti e disponibilità per piano possono cambiare alla fine della beta.
## Come connettersi
* **URL base:** `https://api.squarecloud.app/v2/ai`
* **Chiave API:** la chiave API del tuo account (la stessa usata dall'API di Square Cloud e dalla CLI, dalla [pagina dell'account](https://squarecloud.app/account)). L'header `Authorization` è accettato con o senza il prefisso `Bearer `.
* **Modello:** `cubic`, il modello ospitato da Square Cloud, lo stesso che alimenta l'assistente AI della dashboard.
## Piani e limiti
Ogni richiesta addebita i token effettivamente usati sul **budget giornaliero di token AI** del tuo piano (lo stesso budget usato dall'assistente della dashboard, azzerato alle 00:00 UTC). Standard e Pro hanno anche un tetto giornaliero di richieste, e ogni piano ha una quota giornaliera di fair use sul gateway, dimensionata per un uso moderato (una protezione per le chiavi lasciate senza controllo, basata su quanto costa servire le richieste); entrambi si azzerano alla stessa ora.
| Piano | Richieste al giorno | Quota di fair use | Finestra di contesto | Output massimo | Richieste simultanee | Intervallo tra le richieste |
| - | - | - | - | - | - | - |
| Standard | 1.000 | base | 16.384 token | 4.096 | 1 | 5s |
| Pro | 5.000 | base | 24.576 token | 6.144 | 1 | 2s |
| Enterprise | illimitate | 5x base | 32.768 token | 8.192 | 2 | nessuno |
I piani Hobby (e gli account senza piano) non hanno accesso all'AI Gateway: passare a Standard o superiore lo abilita.
## Contratto della richiesta
Accettato per compatibilità con gli SDK; il gateway risponde sempre come `cubic`.
Messaggi in stile OpenAI con i ruoli `system`, `user`, `assistant` e `tool`. Il contenuto deve essere una **stringa**: questo endpoint è solo testuale, quindi un array multi-part (`image_url`, `input_audio`, `file`) viene rifiutato con `400 multimodal_not_supported`. Fino a **100 messaggi** per richiesta.
Ridotto automaticamente al tetto di output del tuo piano.
Da 0 a 2.
Function calling nel formato standard di OpenAI, fino a **32 definizioni di tool**. Le chiamate ai tool tornano come `finish_reason: "tool_calls"`, e rimandi i risultati come messaggi `role: "tool"`.
Valori standard di `tool_choice` di OpenAI.
I parametri sconosciuti vengono ignorati, con due eccezioni volute: `audio` e un valore di `modalities` diverso da `["text"]` vengono **rifiutati** anziché ignorati, così una richiesta di output vocale non torna mai come testo silenzioso.
**Testo in ingresso, testo in uscita.** Immagini, audio e file non sono accettati su nessun piano, ed è una scelta di prodotto, non una mancanza temporanea. Invia testo e ricevi testo.
**Non ancora supportato:** lo streaming (`stream: true` restituisce `400 stream_not_supported`).
### Ricerca web integrata
Il modello decide da solo di cercare sul web quando la conversazione richiede informazioni attuali o esterne. Le ricerche vengono eseguite lato server e viene restituita solo la risposta finale, con gli URL dei risultati citati. Se dichiari un tuo tool chiamato `web_search`, il tuo sostituisce quello integrato.
```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
}
}
```
## Errori
Ogni errore usa il formato di OpenAI `{ "error": { "message", "type", "param", "code" } }`, inclusi gli errori di autenticazione, scope, rate limit, body non valido, `500` e `503`, e il `code` è sempre in minuscolo.
| Stato | Codice | Significato / cosa fare |
| - | - | - |
| 401 | `access_denied` | La chiave API è mancante, non valida, revocata o scaduta. |
| 403 | `upgrade_required` | Il piano non ha accesso all'AI Gateway (Hobby o nessun piano). Passa a Standard o superiore. |
| 403 | `missing_scope` | La chiave API non ha lo scope richiesto da questo endpoint. |
| 403 | `resource_not_allowed` | La chiave API è limitata a risorse che non coprono questa richiesta. |
| 400 | `invalid_json_body` / `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | Body della richiesta malformato: correggi il campo segnalato. |
| 400 | `stream_not_supported` | Rimuovi `stream: true`; lo streaming non è ancora disponibile. |
| 400 | `multimodal_not_supported` | L'endpoint è solo testuale. Invia il `content` di ogni messaggio come stringa, e rimuovi `audio` o qualsiasi `modalities` oltre a `["text"]`. |
| 400 | `context_length_exceeded` | Messaggi e definizioni dei tool superano la finestra di contesto del piano. Accorcia la cronologia o passa a un piano superiore. |
| 400 | `invalid_request` | Il backend del modello ha rifiutato la richiesta: quasi sempre un errore nel protocollo di tool calling (un messaggio `tool` che non risponde a un `tool_calls` precedente, id di chiamata duplicati). |
| 413 | `payload_too_large` | Il body della richiesta supera la dimensione accettata da questo endpoint. Accorcia la cronologia. |
| 429 | `concurrent_limit_reached` | Una richiesta è già in corso; attendi che finisca (Enterprise ne consente 2 contemporaneamente). |
| 429 | `rate_limit_exceeded` | Richieste inviate più velocemente dell'intervallo previsto dal piano; aggiungi il ritardo lato client. |
| 429 | `daily_request_limit_reached` | È stato raggiunto il tetto giornaliero di richieste del piano (Standard 1.000 / Pro 5.000); si azzera alle 00:00 UTC. Enterprise non ha tetto. |
| 429 | `daily_spend_limit_reached` | È stata raggiunta la quota giornaliera di fair use del piano sul gateway; si azzera alle 00:00 UTC. Enterprise ha 5 volte la quota base. |
| 429 | `daily_limit_reached` | Il budget giornaliero di token AI è esaurito; si azzera alle 00:00 UTC. Un piano superiore aumenta il budget. |
| 429 | `rate_limited` | È stato raggiunto il limite di richieste dell'account o della chiave API; attendi e riprova. |
| 500 | `internal_server_error` | Errore imprevisto. Riprova. |
| 503 | `server_overloaded` | La capacità è momentaneamente piena, oppure la richiesta ha superato la scadenza totale di 90 secondi; riprova a breve (gli SDK di OpenAI lo ritentano automaticamente). |
| 503 | `daily_capacity_reached` | La capacità giornaliera condivisa dell'AI Gateway, per l'intera piattaforma, è esaurita. Si azzera alle 00:00 UTC; ritentare prima non serve. |
| 503 | `database_unavailable` | La piattaforma è momentaneamente non disponibile. Riprova tra qualche secondo. |
Tre di questi si somigliano ma significano cose diverse:
* `429 daily_spend_limit_reached`: il limite giornaliero della **tua** chiave, stabilito dal tuo piano.
* `503 daily_capacity_reached`: la capacità giornaliera della **piattaforma** per il gateway, condivisa da tutti i clienti.
* `503 server_overloaded`: un sovraccarico momentaneo, oppure una richiesta che ha impiegato più di 90 secondi in totale (coda del provider, nuovi tentativi e cicli di ricerca inclusi). Riprova tra qualche secondo.
## Domande frequenti
No, l'API è stateless, esattamente come quella di OpenAI: invia la cronologia della conversazione in `messages` a ogni richiesta.
`cubic`, il modello ospitato da Square Cloud. Non c'è un elenco di modelli tra cui scegliere; il campo `model` è accettato per compatibilità con gli SDK.
Sì, è il caso d'uso principale. È una normale API HTTPS, quindi funziona da qualsiasi luogo.
Sì: entrambi consumano lo stesso budget giornaliero di token AI, quindi un uso intenso del gateway riduce il budget disponibile per l'assistente della dashboard e viceversa.
## Vedi anche
* SDK: [`api.ai.chat()`](/it/sdks/js/ai) (JavaScript), [`client.ai.chat()`](/it/sdks/py/ai) (Python), [`c.AI.Chat()`](/it/sdks/go/ai) (Go)