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.
string
obrigatório
A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.
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). O header
Authorizationé aceito com ou sem o prefixoBearer. - 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.
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
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: 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.number
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.number
Nome legado, ainda aceito. 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.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 chamadaweb_search, a sua substitui a integrada.
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.
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 respostas429 e 503 diz ao seu cliente quando tentar de novo, com headers que os SDKs da OpenAI leem:
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
Ele lembra das conversas?
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?
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?
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?
O uso do gateway afeta meu assistente de IA do dashboard?
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()(JavaScript),client.ai.chat()(Python),c.AI.Chat()(Go)

