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

> Llama al AI Gateway de Square Cloud desde squarecloud-api con client.ai.chat(): chat completions compatibles con OpenAI, sin streaming.

`client.ai.chat(request)` llama al [AI Gateway](/en/api-reference/ai-gateway), un endpoint de chat completions **compatible con OpenAI**. Necesita el scope `ai:chat` y un plan Standard o 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"])
```

## Petición

`request` es un dict que se envía tal cual como cuerpo, así que cualquier otro parámetro de OpenAI pasa sin cambios. Está tipado como `squarecloud.types.ChatRequest`.

| Campo                   | Descripción                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `model`                 | `cubic`. Se acepta por compatibilidad: no hay ningún otro modelo                                    |
| `messages`              | `{ role, content?, tool_call_id?, tool_calls? }`, con `role` `system`, `user`, `assistant` o `tool` |
| `tools` / `tool_choice` | Function calling de OpenAI                                                                          |
| `max_tokens`            | Número máximo de tokens de la respuesta                                                             |
| `temperature`           | Temperatura de muestreo                                                                             |

La respuesta tiene la forma de OpenAI: `id`, `object`, `created`, `model`, `choices` (`index`, `message`, `finish_reason`) y `usage`.

## Sin streaming

`ai.chat()` no hace streaming: devuelve la respuesta completa. `"stream": True` da 400 `stream_not_supported`.

## Timeout

El gateway concede a cada petición **90 segundos** en total y después responde 503 `server_overloaded`. El SDK espera al menos 120 s antes de agotar el tiempo, así que recibes la respuesta del gateway.

## Errores

Los errores de IA usan el formato de OpenAI, así que sus códigos están en **minúsculas**. Aun así lanzan un [`SquareCloudAPIError`](/es/sdks/py/errors), con `code` igual al código de OpenAI (o a su `type` cuando no hay 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
```

| Estado | Código                                                                                                  | Cuándo                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| 400    | `stream_not_supported`                                                                                  | Se envió `stream: true`                                                              |
| 400    | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | Un campo mal formado                                                                 |
| 400    | `context_length_exceeded`                                                                               | La conversación supera la ventana de contexto del plan                               |
| 401    | `access_denied`                                                                                         | Clave de API no válida                                                               |
| 403    | `upgrade_required`                                                                                      | El plan no tiene acceso al AI Gateway                                                |
| 429    | `rate_limit_exceeded`, `concurrent_limit_reached`                                                       | Demasiado rápido, o ya hay una petición en curso                                     |
| 429    | `daily_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached`                       | Se agotó un presupuesto diario (se reinicia a las 00:00 UTC)                         |
| 503    | `server_overloaded`                                                                                     | La capacidad está llena o se superó el plazo de 90 s: se puede reintentar sin riesgo |
| 503    | `daily_capacity_reached`                                                                                | Se agotó la capacidad diaria de la plataforma                                        |

El SDK **nunca reintenta** los errores de IA: la petición es un `POST` no idempotente. Consulta la [referencia del AI Gateway](/en/api-reference/ai-gateway) para ver los límites de cada plan.