> ## 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.

# SDK JavaScript: chat do AI Gateway

> Chame o AI Gateway da Square Cloud a partir do @squarecloud/api com api.ai.chat(): chat completions compatíveis com OpenAI, sem streaming.

`api.ai.chat(request)` chama o [AI Gateway](/pt-br/api-reference/ai-gateway), um endpoint de chat completions **compatível com OpenAI**. Requer o escopo `ai:chat` e um plano Standard ou superior.

Os exemplos usam o cliente `api` de [Criando o cliente](/pt-br/sdks/js/client#criando-o-cliente).

```typescript theme={"system"}
const completion = await api.ai.chat({
    model: "cubic",
    messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "What is Square Cloud?" },
    ],
    max_tokens: 512,
});

console.log(completion.choices[0].message.content);
console.log(completion.usage.total_tokens);
```

## Requisição

| Campo | Descrição |
| - | - |
| `model` | `cubic`. Aceito por compatibilidade: não existe outro modelo |
| `messages` | `{ role, content?, tool_call_id?, tool_calls? }`, com `role` `system`, `user`, `assistant` ou `tool` |
| `tools` / `tool_choice` | Function calling da OpenAI |
| `max_tokens` | Máximo de tokens da resposta |
| `temperature` | Temperatura de amostragem |

A resposta segue o formato da OpenAI: `id`, `object`, `created`, `model`, `choices` (`index`, `message`, `finish_reason`) e `usage`.

## Sem streaming

`ai.chat()` não faz streaming: ele retorna a completion inteira. `stream: true` resulta em 400 `stream_not_supported`.

## Timeout

O gateway dá a cada requisição **90 segundos** no total e então responde 503 `server_overloaded`. O SDK espera pelo menos 120 s antes de expirar, então você recebe a resposta do gateway.

## Erros

Os erros de IA usam o formato da OpenAI, então seus códigos são em **minúsculas**. Eles ainda lançam um [`SquareCloudAPIError`](/pt-br/sdks/js/errors), com `code` definido como o código da OpenAI (ou seu `type` quando não há código):

```typescript theme={"system"}
import { SquareCloudAPIError } from "@squarecloud/api";

try {
    await api.ai.chat({ messages: [{ role: "user", content: "Hi" }] });
} catch (error) {
    if (error instanceof SquareCloudAPIError && error.code === "server_overloaded") {
        // safe to retry yourself
    }
}
```

| Status | Código | Quando |
| - | - | - |
| 400 | `stream_not_supported` | `stream: true` foi enviado |
| 400 | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | Um campo malformado |
| 400 | `context_length_exceeded` | A conversa excede a janela de contexto do plano |
| 401 | `access_denied` | Chave de API inválida |
| 403 | `upgrade_required` | O plano não tem acesso ao AI Gateway |
| 429 | `rate_limit_exceeded`, `concurrent_limit_reached` | Rápido demais, ou uma requisição já em andamento |
| 429 | `daily_limit_reached`, `weekly_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached` | Um limite diário ou semanal foi esgotado (limites diários reiniciam às 00:00 UTC, os semanais na segunda-feira às 00:00 UTC) |
| 503 | `server_overloaded` | A capacidade está cheia ou o prazo de 90 s passou: é seguro tentar novamente |
| 503 | `daily_capacity_reached` | A capacidade diária da plataforma foi esgotada |

O SDK **nunca tenta novamente** erros de IA: a requisição é um `POST` não idempotente. Veja a [referência do AI Gateway](/pt-br/api-reference/ai-gateway) para os limites dos planos.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Erros" icon="triangle-exclamation" href="/pt-br/sdks/js/errors">
    Classe de erro, novas tentativas e rate limits.
  </Card>

  <Card title="Referência do AI Gateway" icon="code" href="/pt-br/api-reference/ai-gateway">
    Modelos, limites por plano e o endpoint compatível com a OpenAI.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.