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

# KI

> Rufe das Square Cloud AI Gateway aus @squarecloud/api mit api.ai.chat() auf: OpenAI-kompatible Chat Completions, ohne Streaming.

`api.ai.chat(request)` ruft das [AI Gateway](/en/api-reference/ai-gateway) auf, einen **OpenAI-kompatiblen** Endpoint für Chat Completions. Dafür sind der Scope `ai:chat` und mindestens ein Standard-Plan nötig.

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

## Anfrage

| Feld                    | Beschreibung                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
| `model`                 | `cubic`. Aus Kompatibilitätsgründen akzeptiert: Es gibt kein anderes Modell                            |
| `messages`              | `{ role, content?, tool_call_id?, tool_calls? }`, mit `role` `system`, `user`, `assistant` oder `tool` |
| `tools` / `tool_choice` | Function Calling von OpenAI                                                                            |
| `max_tokens`            | Maximale Anzahl Tokens der Antwort                                                                     |
| `temperature`           | Sampling-Temperatur                                                                                    |

Die Antwort hat die Form von OpenAI: `id`, `object`, `created`, `model`, `choices` (`index`, `message`, `finish_reason`) und `usage`.

## Kein Streaming

`ai.chat()` streamt nicht: Die Methode gibt die gesamte Completion zurück. `stream: true` ergibt 400 `stream_not_supported`.

## Timeout

Das Gateway gibt jeder Anfrage insgesamt **90 Sekunden** und antwortet danach mit 503 `server_overloaded`. Das SDK wartet mindestens 120 s, bevor ein Timeout eintritt, sodass du die Antwort des Gateways erhältst.

## Fehler

KI-Fehler verwenden das Format von OpenAI, daher sind ihre Codes **kleingeschrieben**. Sie werfen trotzdem einen [`SquareCloudAPIError`](/de/sdks/js/errors), wobei `code` auf den OpenAI-Code gesetzt ist (oder auf seinen `type`, wenn es keinen Code gibt):

```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 | Code                                                                                                    | Wann                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| 400    | `stream_not_supported`                                                                                  | `stream: true` wurde gesendet                                                                           |
| 400    | `invalid_messages`, `invalid_tools`, `invalid_tool_choice`, `invalid_temperature`, `invalid_max_tokens` | Ein fehlerhaftes Feld                                                                                   |
| 400    | `context_length_exceeded`                                                                               | Die Konversation überschreitet das Kontextfenster des Plans                                             |
| 401    | `access_denied`                                                                                         | Ungültiger API-Schlüssel                                                                                |
| 403    | `upgrade_required`                                                                                      | Der Plan hat keinen Zugang zum AI Gateway                                                               |
| 429    | `rate_limit_exceeded`, `concurrent_limit_reached`                                                       | Zu schnell, oder bereits eine laufende Anfrage                                                          |
| 429    | `daily_limit_reached`, `daily_request_limit_reached`, `daily_spend_limit_reached`                       | Ein Tagesbudget ist aufgebraucht (wird um 00:00 UTC zurückgesetzt)                                      |
| 503    | `server_overloaded`                                                                                     | Die Kapazität ist ausgeschöpft oder die Frist von 90 s ist abgelaufen: kann gefahrlos wiederholt werden |
| 503    | `daily_capacity_reached`                                                                                | Die tägliche Kapazität der Plattform ist aufgebraucht                                                   |

Das SDK **wiederholt KI-Fehler nie**: Die Anfrage ist ein nicht idempotenter `POST`. Die Limits der Pläne findest du in der [Referenz des AI Gateway](/en/api-reference/ai-gateway).