> ## 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 api.ai.chat(): chat completions compatibles con OpenAI, sin streaming.

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

```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);
```

## Petición

| 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/js/errors), con `code` igual al código de OpenAI (o a su `type` cuando no hay 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
    }
}
```

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