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

# IA

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

`client.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.

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

print(completion["choices"][0]["message"]["content"])
print(completion["usage"]["total_tokens"])
```

## Requisição

`request` é um dict enviado como corpo, como está, então qualquer outro parâmetro da OpenAI é repassado. Ele é tipado como `squarecloud.types.ChatRequest`.

| 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/py/errors), com `code` definido como o código da OpenAI (ou seu `type` quando não há código):

```python theme={"system"}
from squarecloud import SquareCloudAPIError

try:
    client.ai.chat({"messages": [{"role": "user", "content": "Hi"}]})
except SquareCloudAPIError as error:
    if error.code == "server_overloaded":
        ...  # safe to retry yourself
    else:
        raise
```

| 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`, `daily_request_limit_reached`, `daily_spend_limit_reached`                       | Um orçamento diário foi esgotado (reinicia à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.