AI Gateway (Beta) - Square Cloud

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: "Explique o que é a Square Cloud em uma frase." },
  ],
});

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": "Explique o que é a Square Cloud em uma frase."},
    ],
)

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": "Explique o que é a Square Cloud em uma frase." }
    ]
  }'

{
  "id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
  "object": "chat.completion",
  "created": 1754179200,
  "model": "cubic",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A Square Cloud é uma plataforma de nuvem que hospeda suas aplicações, bots, sites e bancos de dados sem nenhuma configuração de infraestrutura."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 24,
    "total_tokens": 52
  }
}

string

obrigatório

A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.

O AI Gateway permite usar o modelo de IA hospedado da Square Cloud dentro dos seus próprios produtos — chatbots, assistentes, automações — através de um endpoint de chat completions compatível com OpenAI. Se o seu código já fala a API da OpenAI, ele fala com o AI Gateway também: aponte o SDK para a nossa base URL, use a API key da sua conta e defina o modelo como cubic.

O AI Gateway está em beta com acesso antecipado gratuito: durante o beta não há cobrança extra além do orçamento diário de tokens de IA do seu plano. Limites e disponibilidade por plano podem mudar quando o beta terminar.

Como conectar

Base URL: https://api.squarecloud.app/v2/ai
API key: a API key da sua conta (a mesma usada pela API e CLI da Square Cloud, disponível na página da conta). O header Authorization é aceito com ou sem o prefixo Bearer .
Modelo: cubic — o modelo hospedado da Square Cloud, o mesmo que alimenta o assistente de IA do dashboard.

Planos e limites

As requisições são ilimitadas; cada requisição cobra os tokens reais do orçamento diário de tokens de IA do seu plano (o mesmo orçamento do assistente do dashboard, com reset às 00:00 UTC).

Plano	Janela de contexto	Saída máxima	Requisições simultâneas	Intervalo entre requisições
Standard	16.384 tokens	4.096	1	4s
Pro	24.576 tokens	6.144	1	2s
Enterprise	32.768 tokens	8.192	2	nenhum

Planos Hobby (e contas sem plano) não têm acesso ao AI Gateway — o upgrade para Standard ou superior habilita o acesso.

Contrato da requisição

string

Aceito por compatibilidade com SDKs; o gateway sempre responde como cubic.

array

obrigatório

Mensagens no estilo OpenAI com os papéis system, user, assistant e tool. O conteúdo deve ser uma string (sem imagens/visão por enquanto). Até 100 mensagens por requisição.

number

Limitado silenciosamente ao teto de saída do seu plano.

number

De 0 a 2.

array

Function calling no formato padrão da OpenAI, com até 32 definições de tools. As chamadas de tool retornam como finish_reason: "tool_calls", e você envia os resultados de volta como mensagens role: "tool".

string | object

Valores padrão de tool_choice da OpenAI.

Parâmetros desconhecidos são ignorados. Ainda não suportado: streaming (stream: true retorna 400 stream_not_supported) e imagens/visão.

Busca na web integrada

O modelo decide sozinho buscar na web quando a conversa pede informações atuais ou externas. As buscas rodam no servidor, e apenas a resposta final é retornada, citando as URLs dos resultados. Se você declarar uma tool própria chamada web_search, a sua substitui a integrada.

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: "Explique o que é a Square Cloud em uma frase." },
  ],
});

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": "Explique o que é a Square Cloud em uma frase."},
    ],
)

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": "Explique o que é a Square Cloud em uma frase." }
    ]
  }'

{
  "id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
  "object": "chat.completion",
  "created": 1754179200,
  "model": "cubic",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A Square Cloud é uma plataforma de nuvem que hospeda suas aplicações, bots, sites e bancos de dados sem nenhuma configuração de infraestrutura."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 24,
    "total_tokens": 52
  }
}

Erros

Os erros usam o formato da OpenAI: { "error": { "message", "type", "code" } }.

Status	Código	O que significa / o que fazer
403	`upgrade_required`	O plano não tem acesso ao AI Gateway (Hobby ou sem plano). Faça upgrade para Standard ou superior.
400	`invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens`	Corpo da requisição malformado — corrija o campo indicado.
400	`stream_not_supported`	Remova `stream: true`; streaming ainda não está disponível.
400	`context_length_exceeded`	As mensagens mais as definições de tools excedem a janela de contexto do plano. Encurte o histórico ou faça upgrade.
400	`invalid_request`	O backend do modelo recusou a requisição — quase sempre um erro de protocolo de tool calling (uma mensagem `tool` que não responde a um `tool_calls` anterior, ids de chamada duplicados).
429	`concurrent_limit_reached`	Já existe uma requisição em andamento; aguarde ela terminar (Enterprise permite 2 ao mesmo tempo).
429	`rate_limit_exceeded`	Requisições enviadas mais rápido que o intervalo do plano; adicione o delay no cliente.
429	`daily_limit_reached`	O orçamento diário de tokens de IA acabou; ele reseta às 00:00 UTC. Um upgrade aumenta o orçamento.
503	`server_overloaded`	A capacidade está momentaneamente cheia; tente novamente em instantes (SDKs da OpenAI fazem retry automaticamente).

Perguntas frequentes

Ele lembra das conversas?

Não — a API é stateless, exatamente como a da OpenAI: envie o histórico da conversa em messages a cada requisição.

Qual modelo é usado?

cubic, o modelo hospedado da Square Cloud. Não há lista de modelos para escolher; o campo model é aceito por compatibilidade com SDKs.

Posso chamar a partir de uma aplicação hospedada na Square Cloud?

Sim — esse é o principal caso de uso. É uma API HTTPS normal, então funciona de qualquer lugar.

O uso do gateway afeta meu assistente de IA do dashboard?

Sim: ambos consomem o mesmo orçamento diário de tokens de IA, então uso pesado do gateway drena o orçamento disponível para o assistente do dashboard e vice-versa.

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: "Explique o que é a Square Cloud em uma frase." },
  ],
});

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": "Explique o que é a Square Cloud em uma frase."},
    ],
)

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": "Explique o que é a Square Cloud em uma frase." }
    ]
  }'

{
  "id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
  "object": "chat.completion",
  "created": 1754179200,
  "model": "cubic",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A Square Cloud é uma plataforma de nuvem que hospeda suas aplicações, bots, sites e bancos de dados sem nenhuma configuração de infraestrutura."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 24,
    "total_tokens": 52
  }
}

​Como conectar

​Planos e limites

​Contrato da requisição

​Busca na web integrada

​Erros

​Perguntas frequentes

Como conectar

Planos e limites

Contrato da requisição

Busca na web integrada

Erros

Perguntas frequentes