Skip to main content
string
obrigatório
A chave da API para sua conta. Você pode encontrá-la nas configurações da conta.
Requer uma chave de API com o escopo 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 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. 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.
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.

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 respostas 429 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

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