> ## 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 (Beta) > Esta documentação fornece uma visão geral completa do AI Gateway, a API de chat completions compatível com OpenAI da Square Cloud. A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security). 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](https://squarecloud.app/account)). 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 Aceito por compatibilidade com SDKs; o gateway sempre responde como `cubic`. 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. Limitado silenciosamente ao teto de saída do seu plano. De 0 a 2. 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"`. 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. ```javascript JavaScript (OpenAI SDK) theme={null} 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); ``` ```python Python (OpenAI SDK) theme={null} 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) ``` ```bash cURL theme={null} 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." } ] }' ``` ```json theme={null} { "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 Não — a API é stateless, exatamente como a da OpenAI: envie o histórico da conversa em `messages` a cada requisição. `cubic`, o modelo hospedado da Square Cloud. Não há lista de modelos para escolher; o campo `model` é aceito por compatibilidade com SDKs. Sim — esse é o principal caso de uso. É uma API HTTPS normal, então funciona de qualquer lugar. 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.