> ## 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 client.ai.chat() auf: OpenAI-kompatible Chat Completions, ohne Streaming.

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

```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"])
```

## Anfrage

`request` ist ein Dict, das unverändert als Body gesendet wird, sodass jeder andere OpenAI-Parameter durchgereicht wird. Es ist als `squarecloud.types.ChatRequest` typisiert.

| 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/py/errors), wobei `code` auf den OpenAI-Code gesetzt ist (oder auf seinen `type`, wenn es keinen Code gibt):

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