> ## 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 compatível com OpenAI (beta) > Use o modelo cubic da Square Cloud nos seus próprios produtos pelo POST /v2/ai/chat/completions, compatível com OpenAI, com tool calling e busca na web. A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security). Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `ai:chat`. 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, e o uso conta apenas para os limites de tokens próprios do gateway. 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 Cada requisição cobra os tokens reais dos **limites de tokens próprios do gateway**: um limite diário, com reset às 00:00 UTC, e um limite semanal de 4x o diário, com reset na segunda-feira às 00:00 UTC. Eles são separados dos limites do assistente de IA do dashboard, então o tráfego do gateway nunca consome a franquia do assistente, e vice-versa. Standard e Pro também têm um teto diário de requisições, e todos os planos têm uma franquia diária de uso justo no gateway, dimensionada para uso moderado (uma proteção para chaves não supervisionadas, baseada no custo de atender as requisições); ambos resetam às 00:00 UTC. | Plano | Tokens por dia | Tokens por semana | Requisições por dia | Franquia de uso justo | Janela de contexto | Saída máxima | Requisições simultâneas | Intervalo entre requisições | | - | - | - | - | - | - | - | - | - | | Standard | 2,5M | 10M | 1.000 | base | 16.384 tokens | 4.096 | 1 | 5s | | Pro | 5M | 20M | 5.000 | 2x a base | 24.576 tokens | 6.144 | 1 | 2s | | Enterprise | 10M a 20M | 40M a 80M | ilimitadas | 5x a base | 32.768 tokens | 8.192 | 2 | nenhum | Todos os tamanhos do plano Standard têm os mesmos limites no gateway, assim como todos os tamanhos do Pro. Os limites de tokens do Enterprise crescem com o plano: 10M tokens por dia no Enterprise 32, 12M no Enterprise 48, 14M no Enterprise 64, 16M no Enterprise 96 e 20M no Enterprise 128 ou superior, com 4x isso por semana. 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**: este endpoint aceita apenas texto, então um array multi-parte (`image_url`, `input_audio`, `file`) é recusado com `400 multimodal_not_supported`. Até **100 mensagens** por requisição. Nome atual da OpenAI para o limite de tokens da resposta, o que os SDKs da OpenAI enviam. Vale sobre o `max_tokens` quando os dois vêm juntos. Limitado silenciosamente ao teto de saída do seu plano. Nome legado, ainda aceito. 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, com duas exceções deliberadas: `audio` e um `modalities` diferente de `["text"]` são **recusados** em vez de ignorados, para que um pedido de resposta em áudio nunca volte como texto silenciosamente. **Texto na entrada, texto na saída.** Imagens, áudio e arquivos não são aceitos em nenhum plano, e isso é uma decisão de produto, não uma limitação temporária. Envie texto e leia texto de volta. **Ainda não suportado:** streaming (`stream: true` retorna `400 stream_not_supported`). ### 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={"system"} 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={"system"} 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={"system"} 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={"system"} { "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 Todo erro usa o formato da OpenAI `{ "error": { "message", "type", "param", "code" } }`, incluindo erros de autenticação, escopo, limite de requisições, corpo inválido, `500` e `503`, e o `code` é sempre em minúsculas. | Status | Código | O que significa / o que fazer | | - | - | - | | 401 | `access_denied` | A API key está ausente, é inválida, foi revogada ou expirou. | | 403 | `upgrade_required` | O plano não tem acesso ao AI Gateway (Hobby ou sem plano). Faça upgrade para Standard ou superior. | | 403 | `missing_scope` | A API key não tem o escopo que este endpoint exige. | | 403 | `resource_not_allowed` | A API key está restrita a recursos que não cobrem esta requisição. | | 400 | `invalid_json_body` / `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 | `multimodal_not_supported` | O endpoint aceita apenas texto. Envie o `content` de cada mensagem como string e remova `audio` ou qualquer `modalities` além de `["text"]`. | | 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). | | 413 | `payload_too_large` | O corpo da requisição é maior do que este endpoint aceita. Encurte o histórico. | | 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_request_limit_reached` | O teto diário de requisições do plano foi atingido (Standard 1.000 / Pro 5.000); ele reseta às 00:00 UTC. Enterprise não tem teto. | | 429 | `daily_spend_limit_reached` | A franquia diária de uso justo do plano no gateway foi atingida; ela reseta às 00:00 UTC. Pro tem 2x e Enterprise 5x a franquia base. | | 429 | `daily_limit_reached` | O limite diário de tokens do gateway acabou; ele reseta às 00:00 UTC. Um upgrade aumenta o limite. | | 429 | `weekly_limit_reached` | O limite semanal de tokens do gateway (4x o diário) acabou; ele reseta na segunda-feira às 00:00 UTC. Um upgrade aumenta o limite. | | 429 | `rate_limited` | O limite de requisições da conta ou da API key foi atingido; aguarde e tente novamente. | | 500 | `internal_server_error` | Falha inesperada. Tente novamente. | | 503 | `server_overloaded` | A capacidade está momentaneamente cheia, ou a requisição passou do prazo total de 90 segundos; tente novamente em instantes (SDKs da OpenAI fazem retry automaticamente). | | 503 | `daily_capacity_reached` | A capacidade diária compartilhada do AI Gateway, para toda a plataforma, se esgotou. Ela reseta às 00:00 UTC; tentar de novo antes disso não adianta. | | 503 | `database_unavailable` | A plataforma está brevemente indisponível. Tente novamente em alguns segundos. | Três desses códigos parecem iguais, mas significam coisas diferentes: * `429 daily_spend_limit_reached`: o limite diário da **sua** chave, definido pelo seu plano. * `503 daily_capacity_reached`: a capacidade diária da **plataforma** para o gateway, compartilhada por todos os clientes. * `503 server_overloaded`: uma sobrecarga momentânea, ou uma requisição que levou mais de 90 segundos no total (fila do provedor, retries e rodadas de busca incluídos). Tente novamente em alguns segundos. ## Novas tentativas A maioria das respostas `429` e `503` diz ao seu cliente quando tentar de novo, com headers que os SDKs da OpenAI leem: | Código | Headers | O que esperar | | - | - | - | | `429 rate_limit_exceeded` | `Retry-After` com o intervalo do plano entre requisições, em segundos (Standard 5, Pro 2) | Os SDKs da OpenAI esperam e tentam de novo sozinhos. | | `429 daily_request_limit_reached`, `daily_spend_limit_reached`, `daily_limit_reached` e `503 daily_capacity_reached` | `Retry-After` com os segundos até 00:00 UTC, e `x-should-retry: false` | O SDK não tenta de novo; aguarde o limite resetar. | | `429 weekly_limit_reached` | `Retry-After` com os segundos até segunda-feira às 00:00 UTC, e `x-should-retry: false` | O SDK não tenta de novo; aguarde o limite resetar. | | `503 server_overloaded` | `Retry-After: 2` | Os SDKs da OpenAI esperam e tentam de novo sozinhos. | | `429 concurrent_limit_reached` | Sem `Retry-After` | Tente de novo quando a requisição em andamento terminar, ou deixe as novas tentativas padrão do SDK cuidarem disso. | Os SDKs da OpenAI respeitam um `Retry-After` de até 60 segundos. Uma espera maior cai no backoff do próprio SDK, a menos que a resposta também traga `x-should-retry: false`, que desliga as novas tentativas automáticas. Sem um SDK da OpenAI, leia o `Retry-After` você mesmo e espere esses segundos antes da próxima requisição. ## 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. Não. O gateway tem seus próprios limites diário e semanal de tokens, separados dos do assistente do dashboard, então uso pesado do gateway nunca consome a franquia do assistente, e vice-versa. ## Relacionados * SDKs: [`api.ai.chat()`](/pt-br/sdks/js/ai) (JavaScript), [`client.ai.chat()`](/pt-br/sdks/py/ai) (Python), [`c.AI.Chat()`](/pt-br/sdks/go/ai) (Go) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.