AI Gateway compatibile con OpenAI (Beta)

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

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

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

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.

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

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

Ricorda le conversazioni?

No, l’API è stateless, esattamente come quella di OpenAI: invia la cronologia della conversazione in messages a ogni richiesta.

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?

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?

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() (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
  }
}

Primi passi

Account

Applicazioni

Database

Workspace

IA

AI Gateway compatibile con OpenAI (Beta)

Come connettersi

Piani e limiti

Contratto della richiesta

Ricerca web integrata

Errori

Domande frequenti

Vedi anche

​Come connettersi

​Piani e limiti

​Contratto della richiesta

​Ricerca web integrata

​Errori

​Domande frequenti

​Vedi anche

Come connettersi

Piani e limiti

Contratto della richiesta

Ricerca web integrata

Errori

Domande frequenti

Vedi anche