Vai al contenuto principale
string
obbligatorio
La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.
Richiede una chiave API con lo 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, 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 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 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.
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.

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 risposte 429 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

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