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.
string
obbligatorio
La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.
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, e l’uso conta solo sui limiti di token propri del gateway. 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). L’header
Authorizationè accettato con o senza il prefissoBearer. - 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 sui limiti di token propri del gateway: un limite giornaliero, azzerato alle 00:00 UTC, e un limite settimanale pari a 4 volte quello giornaliero, azzerato il lunedì alle 00:00 UTC. Sono separati dai limiti dell’assistente AI della dashboard, quindi il traffico del gateway non consuma mai la quota dell’assistente, e viceversa. 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 alle 00:00 UTC.
Tutte le taglie del piano Standard hanno gli stessi limiti sul gateway, e lo stesso vale per tutte le taglie di Pro. I limiti di token di Enterprise crescono con il piano: 10M token al giorno su Enterprise 32, 12M su Enterprise 48, 14M su Enterprise 64, 16M su Enterprise 96 e 20M su Enterprise 128 e superiori, con 4 volte tanto a settimana.
I piani Hobby (e gli account senza piano) non hanno accesso all’AI Gateway: passare a Standard o superiore lo abilita.
Contratto della richiesta
string
Accettato per compatibilità con gli SDK; il gateway risponde sempre come
cubic.array
obbligatorio
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.number
Il nome attuale di OpenAI per il limite di token della risposta, quello inviato dagli SDK di OpenAI. Prevale su
max_tokens quando ci sono entrambi. Ridotto automaticamente al tetto di output del tuo piano.number
Il nome precedente, ancora accettato. Ridotto automaticamente al tetto di output del tuo piano.
number
Da 0 a 2.
array
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".string | object
Valori standard di
tool_choice di OpenAI.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 chiamatoweb_search, il tuo sostituisce quello integrato.
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.
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.
Nuovi tentativi
La maggior parte delle risposte429 e 503 dice al tuo client quando riprovare, con header che gli SDK di OpenAI leggono:
Gli SDK di OpenAI rispettano un
Retry-After fino a 60 secondi. Un’attesa più lunga passa al backoff dell’SDK stesso, a meno che la risposta non contenga anche x-should-retry: false, che disattiva i nuovi tentativi automatici. Senza un SDK di OpenAI, leggi tu Retry-After e attendi quei secondi prima della richiesta successiva.
Domande frequenti
Ricorda le conversazioni?
Ricorda le conversazioni?
No, l’API è stateless, esattamente come quella di OpenAI: invia la cronologia della conversazione in
messages a ogni richiesta.Quale modello è?
Quale modello è?
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.Posso chiamarlo da un'app ospitata su Square Cloud?
Posso chiamarlo da un'app ospitata su Square Cloud?
Sì, è il caso d’uso principale. È una normale API HTTPS, quindi funziona da qualsiasi luogo.
L'uso del gateway influisce sull'assistente AI della dashboard?
L'uso del gateway influisce sull'assistente AI della dashboard?
No. Il gateway ha i propri limiti giornaliero e settimanale di token, separati da quelli dell’assistente della dashboard, quindi un uso intenso del gateway non consuma mai la quota dell’assistente, e viceversa.
Vedi anche
- SDK:
api.ai.chat()(JavaScript),client.ai.chat()(Python),c.AI.Chat()(Go)

