OpenAI-kompatibles AI Gateway (Beta)

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

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)

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." }
    ]
  }'

{
  "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
  }
}

string

erforderlich

Der API-Schlüssel für dein Konto. Du findest ihn in deinen Kontoeinstellungen.

Erfordert einen API-Schlüssel mit dem Scope 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). 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

string

Wird aus Kompatibilitätsgründen mit SDKs akzeptiert; das Gateway antwortet immer als cubic.

array

erforderlich

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.

number

Wird stillschweigend auf die Ausgabegrenze deines Plans begrenzt.

number

Von 0 bis 2.

array

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.

string | object

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.

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

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)

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." }
    ]
  }'

{
  "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

Merkt es sich Gespräche?

Nein, die API ist zustandslos, genau wie die von OpenAI: Sende den Gesprächsverlauf bei jeder Anfrage in messages.

Welches Modell ist es?

cubic, das gehostete Modell von Square Cloud. Es gibt keine Modellliste zur Auswahl; das Feld model wird aus Kompatibilitätsgründen mit SDKs akzeptiert.

Kann ich es aus einer auf Square Cloud gehosteten Anwendung aufrufen?

Ja, das ist der wichtigste Anwendungsfall. Es ist eine normale HTTPS-API und funktioniert daher von überall.

Wirkt sich die Nutzung des Gateways auf meinen KI-Assistenten im Dashboard aus?

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() (JavaScript), client.ai.chat() (Python), c.AI.Chat() (Go)

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

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)

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." }
    ]
  }'

{
  "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
  }
}

Erste Schritte

Konto

Anwendungen

Datenbanken

Workspaces

KI

OpenAI-kompatibles AI Gateway (Beta)

Verbindung herstellen

Pläne und Limits

Anfrageformat

Integrierte Websuche

Fehler

Häufige Fragen

Siehe auch

​Verbindung herstellen

​Pläne und Limits

​Anfrageformat

​Integrierte Websuche

​Fehler

​Häufige Fragen

​Siehe auch

Verbindung herstellen

Pläne und Limits

Anfrageformat

Integrierte Websuche

Fehler

Häufige Fragen

Siehe auch