> ## 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 dem Go SDK mit c.AI.Chat auf: OpenAI-kompatible Chat Completions, ohne Streaming.

`c.AI.Chat(ctx, 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.

```go theme={"system"}
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

func main() {
	ctx := context.Background()
	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))

	completion, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
		Model: "cubic",
		Messages: []squarecloud.ChatMessage{
			{Role: "system", Content: "You are a helpful assistant."},
			{Role: "user", Content: "What is Square Cloud?"},
		},
		MaxTokens: 512,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
	fmt.Println(completion.Usage.TotalTokens)
}
```

## Anfrage

Die Felder von `squarecloud.ChatRequest` mit ihren JSON-Namen:

| Feld                                             | Beschreibung                                                                                                                                                                                        |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Model` (`model`)                                | `cubic`. Aus Kompatibilitätsgründen akzeptiert: Es gibt kein anderes Modell. `""` wird nicht gesendet                                                                                               |
| `Messages` (`messages`)                          | `[]ChatMessage` mit `Role`, `Content`, `ToolCallID` (`tool_call_id`) und `ToolCalls` (`tool_calls`). `Role` ist `system`, `user`, `assistant` oder `tool`. `Content` wird immer gesendet, auch `""` |
| `Tools` / `ToolChoice` (`tools` / `tool_choice`) | Function Calling von OpenAI: `Tools` ist ein `[]json.RawMessage`, `ToolChoice` ein beliebiger JSON-kodierbarer Wert                                                                                 |
| `MaxTokens` (`max_tokens`)                       | Maximale Anzahl Tokens der Antwort. `0` wird nicht gesendet                                                                                                                                         |
| `Temperature` (`temperature`)                    | Sampling-Temperatur, ein `*float64`. `nil` wird nicht gesendet                                                                                                                                      |

Die Antwort ist eine `ChatCompletion` in der Form von OpenAI: `ID`, `Object`, `Created`, `Model`, `Choices` (`Index`, `Message`, `FinishReason`) und `Usage` (`PromptTokens`, `CompletionTokens`, `TotalTokens`).

## Kein Streaming

`AI.Chat` streamt nicht: Die Methode gibt die gesamte Completion zurück. `ChatRequest` hat kein `stream`-Feld; die API antwortet auf `stream: true` mit 400 `stream_not_supported`.

## Timeout

Das Gateway gibt jeder Anfrage insgesamt **90 Sekunden** und antwortet danach mit 503 `server_overloaded`. Ohne Deadline auf `ctx` wartet das SDK mindestens 2 Minuten, 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 werden trotzdem als [`*APIError`](/de/sdks/go/errors) zurückgegeben, wobei `Code` auf den OpenAI-Code gesetzt ist (oder auf seinen `type`, wenn es keinen Code gibt):

```go theme={"system"}
_, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
	Messages: []squarecloud.ChatMessage{{Role: "user", Content: "Hi"}},
})

var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.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).