> ## 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.
# OpenAI-kompatibles AI Gateway (Beta)
> Nutze das gehostete Modell cubic von Square Cloud in eigenen Produkten über das OpenAI-kompatible POST /v2/ai/chat/completions, mit Tool Calling und Websuche.
Der API-Schlüssel für dein Konto. Du findest ihn in deinen [Kontoeinstellungen](https://squarecloud.app/de/account/security).
Erfordert einen API-Schlüssel mit dem [Scope](/de/api-reference/authentication#scopes) `ai:chat`.
Mit dem AI Gateway nutzt du das gehostete KI-Modell von Square Cloud in deinen **eigenen** Produkten (Chatbots, Assistenten, Automatisierungen) über einen **OpenAI-kompatiblen** Chat-Completions-Endpoint. Spricht dein Code bereits die OpenAI API, spricht er auch das AI Gateway: Richte das SDK auf unsere Basis-URL, verwende den API-Schlüssel deines Kontos und setze das Modell auf `cubic`.
Das AI Gateway ist in der **Beta mit kostenlosem Frühzugang**: Während der Beta fallen über das tägliche KI-Tokenbudget deines Plans hinaus keine zusätzlichen Kosten an. Limits und Verfügbarkeit je Plan können sich mit dem Ende der Beta ändern.
## Verbindung herstellen
* **Basis-URL:** `https://api.squarecloud.app/v2/ai`
* **API-Schlüssel:** der API-Schlüssel deines Kontos (derselbe, den die Square Cloud API und die CLI verwenden, von der [Kontoseite](https://squarecloud.app/account)). Der Header `Authorization` wird mit oder ohne Präfix `Bearer ` akzeptiert.
* **Modell:** `cubic`, das gehostete Modell von Square Cloud, dasselbe, das den KI-Assistenten im Dashboard antreibt.
## Pläne und Limits
Jede Anfrage verrechnet ihre tatsächlichen Tokens mit dem **täglichen KI-Tokenbudget** deines Plans (demselben Budget, das der Dashboard-Assistent nutzt, zurückgesetzt um 00:00 UTC). Standard und Pro haben zusätzlich eine tägliche Obergrenze für Anfragen, und jeder Plan hat im Gateway ein tägliches Fair-Use-Kontingent, bemessen für moderate Nutzung (ein Schutz für unbeaufsichtigte Schlüssel, basierend auf den Kosten der Anfragen); beide werden zur selben Zeit zurückgesetzt.
| Plan | Anfragen pro Tag | Fair-Use-Kontingent | Kontextfenster | Max. Ausgabe | Gleichzeitige Anfragen | Abstand zwischen Anfragen |
| - | - | - | - | - | - | - |
| Standard | 1.000 | Basis | 16.384 Tokens | 4.096 | 1 | 5s |
| Pro | 5.000 | Basis | 24.576 Tokens | 6.144 | 1 | 2s |
| Enterprise | unbegrenzt | 5x Basis | 32.768 Tokens | 8.192 | 2 | keiner |
Hobby-Pläne (und Konten ohne Plan) haben keinen Zugriff auf das AI Gateway: Ein Upgrade auf Standard oder höher schaltet ihn frei.
## Anfrageformat
Wird aus Kompatibilitätsgründen mit SDKs akzeptiert; das Gateway antwortet immer als `cubic`.
Nachrichten im OpenAI-Stil mit den Rollen `system`, `user`, `assistant` und `tool`. Der Inhalt muss ein **String** sein: Dieser Endpoint verarbeitet nur Text, ein mehrteiliges Array (`image_url`, `input_audio`, `file`) wird daher mit `400 multimodal_not_supported` abgelehnt. Bis zu **100 Nachrichten** pro Anfrage.
Wird stillschweigend auf die Ausgabegrenze deines Plans begrenzt.
Von 0 bis 2.
Function Calling im Standardformat von OpenAI, bis zu **32 Tool-Definitionen**. Tool-Aufrufe kommen als `finish_reason: "tool_calls"` zurück, und du sendest die Ergebnisse als Nachrichten mit `role: "tool"` zurück.
Standardwerte von OpenAI für `tool_choice`.
Unbekannte Parameter werden ignoriert, mit zwei bewussten Ausnahmen: `audio` und ein Wert für `modalities` außer `["text"]` werden **abgelehnt** statt ignoriert, damit eine Anfrage nach gesprochener Ausgabe nie stillschweigend als Text zurückkommt.
**Text rein, Text raus.** Bilder, Audio und Dateien werden in keinem Plan angenommen, und das ist eine Produktentscheidung, keine vorübergehende Lücke. Sende Text und lies Text zurück.
**Noch nicht unterstützt:** Streaming (`stream: true` liefert `400 stream_not_supported`).
### Integrierte Websuche
Das Modell entscheidet selbst, im Web zu suchen, wenn das Gespräch nach aktuellen oder externen Informationen fragt. Die Suchen laufen serverseitig, und nur die endgültige Antwort wird zurückgegeben, mit Verweisen auf die Ergebnis-URLs. Deklarierst du ein eigenes Tool namens `web_search`, ersetzt deines das integrierte.
```javascript JavaScript (OpenAI SDK) theme={"system"}
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.squarecloud.app/v2/ai",
apiKey: process.env.SQUARECLOUD_API_KEY,
});
const completion = await client.chat.completions.create({
model: "cubic",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Explain what Square Cloud is in one sentence." },
],
});
console.log(completion.choices[0].message.content);
```
```python Python (OpenAI SDK) theme={"system"}
from openai import OpenAI
client = OpenAI(
base_url="https://api.squarecloud.app/v2/ai",
api_key="YOUR_API_KEY",
)
completion = client.chat.completions.create(
model="cubic",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain what Square Cloud is in one sentence."},
],
)
print(completion.choices[0].message.content)
```
```bash cURL theme={"system"}
curl --request POST \
--url https://api.squarecloud.app/v2/ai/chat/completions \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "cubic",
"messages": [
{ "role": "user", "content": "Explain what Square Cloud is in one sentence." }
]
}'
```
```json theme={"system"}
{
"id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
"object": "chat.completion",
"created": 1754179200,
"model": "cubic",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Square Cloud is a cloud platform that hosts your applications, bots, websites and databases with zero infrastructure setup."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 24,
"total_tokens": 52
}
}
```
## Fehler
Jeder Fehler verwendet die OpenAI-Form `{ "error": { "message", "type", "param", "code" } }`, auch bei Fehlern zu Authentifizierung, Scope, Rate Limit, ungültigem Body, `500` und `503`, und der `code` ist immer kleingeschrieben.
| Status | Code | Bedeutung / was zu tun ist |
| - | - | - |
| 401 | `access_denied` | Der API-Schlüssel fehlt, ist ungültig, widerrufen oder abgelaufen. |
| 403 | `upgrade_required` | Der Plan hat keinen Zugriff auf das AI Gateway (Hobby oder kein Plan). Upgrade auf Standard oder höher. |
| 403 | `missing_scope` | Dem API-Schlüssel fehlt der Scope, den dieser Endpoint braucht. |
| 403 | `resource_not_allowed` | Der API-Schlüssel ist auf Ressourcen beschränkt, die diese Anfrage nicht abdecken. |
| 400 | `invalid_json_body` / `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | Fehlerhafter Request-Body: Korrigiere das bemängelte Feld. |
| 400 | `stream_not_supported` | Entferne `stream: true`; Streaming ist noch nicht verfügbar. |
| 400 | `multimodal_not_supported` | Der Endpoint verarbeitet nur Text. Sende den `content` jeder Nachricht als String und lass `audio` sowie jede `modalities` außer `["text"]` weg. |
| 400 | `context_length_exceeded` | Nachrichten plus Tool-Definitionen überschreiten das Kontextfenster des Plans. Kürze den Verlauf oder upgrade. |
| 400 | `invalid_request` | Das Modell-Backend hat die Anfrage abgelehnt: fast immer ein Fehler im Tool-Calling-Protokoll (eine `tool`-Nachricht, die auf keinen vorherigen `tool_calls` antwortet, doppelte Call-IDs). |
| 413 | `payload_too_large` | Der Request-Body ist größer, als dieser Endpoint annimmt. Kürze den Verlauf. |
| 429 | `concurrent_limit_reached` | Eine Anfrage läuft bereits; warte, bis sie fertig ist (Enterprise erlaubt 2 gleichzeitig). |
| 429 | `rate_limit_exceeded` | Anfragen schneller gesendet, als der Plan erlaubt; baue die Verzögerung clientseitig ein. |
| 429 | `daily_request_limit_reached` | Die tägliche Anfrageobergrenze des Plans ist erreicht (Standard 1.000 / Pro 5.000); sie wird um 00:00 UTC zurückgesetzt. Enterprise hat keine Obergrenze. |
| 429 | `daily_spend_limit_reached` | Das tägliche Fair-Use-Kontingent des Plans im Gateway ist erreicht; es wird um 00:00 UTC zurückgesetzt. Enterprise hat das 5-Fache des Basiskontingents. |
| 429 | `daily_limit_reached` | Das tägliche KI-Tokenbudget ist aufgebraucht; es wird um 00:00 UTC zurückgesetzt. Ein Upgrade erhöht das Budget. |
| 429 | `rate_limited` | Das Anfragelimit des Kontos oder API-Schlüssels wurde erreicht; warte und versuche es erneut. |
| 500 | `internal_server_error` | Unerwarteter Fehler. Versuche es erneut. |
| 503 | `server_overloaded` | Die Kapazität ist gerade ausgeschöpft, oder die Anfrage hat die Gesamtfrist von 90 Sekunden überschritten; versuche es in Kürze erneut (OpenAI SDKs wiederholen das automatisch). |
| 503 | `daily_capacity_reached` | Die gemeinsame Tageskapazität des AI Gateway für die gesamte Plattform ist aufgebraucht. Sie wird um 00:00 UTC zurückgesetzt; vorher hilft ein erneuter Versuch nicht. |
| 503 | `database_unavailable` | Die Plattform ist kurzzeitig nicht verfügbar. Versuche es in einigen Sekunden erneut. |
Drei davon sehen ähnlich aus, bedeuten aber Verschiedenes:
* `429 daily_spend_limit_reached`: das Tageslimit **deines** Schlüssels, von deinem Plan festgelegt.
* `503 daily_capacity_reached`: die Tageskapazität der **Plattform** für das Gateway, geteilt von allen Kunden.
* `503 server_overloaded`: eine kurzzeitige Überlastung oder eine Anfrage, die insgesamt länger als 90 Sekunden gedauert hat (Warteschlange des Providers, Wiederholungen und Suchrunden eingeschlossen). Versuche es in einigen Sekunden erneut.
## Häufige Fragen
Nein, die API ist zustandslos, genau wie die von OpenAI: Sende den Gesprächsverlauf bei jeder Anfrage in `messages`.
`cubic`, das gehostete Modell von Square Cloud. Es gibt keine Modellliste zur Auswahl; das Feld `model` wird aus Kompatibilitätsgründen mit SDKs akzeptiert.
Ja, das ist der wichtigste Anwendungsfall. Es ist eine normale HTTPS-API und funktioniert daher von überall.
Ja: Beide verbrauchen dasselbe tägliche KI-Tokenbudget, starke Nutzung des Gateways verringert also das Budget für den Dashboard-Assistenten und umgekehrt.
## Siehe auch
* SDKs: [`api.ai.chat()`](/de/sdks/js/ai) (JavaScript), [`client.ai.chat()`](/de/sdks/py/ai) (Python), [`c.AI.Chat()`](/de/sdks/go/ai) (Go)