API-Referenz

Grundlagen der Integration

#Base URL

Alle Endpunkte liegen unter /v1 auf der eigenen Domain dieses Deployments. Es gibt keine Regionsauswahl — das Routing zu Upstream-Anbietern erfolgt hinter dem Gateway.

#Authentifizierungs-Header

Ein einziger Authorization: Bearer-Header ist die gesamte Authentifizierung. Keine Signatur, kein Zeitstempel, kein Header pro Nutzer — alles, was andere Gateways über das Bearer-Token hinaus verlangen, gibt es hier nicht.

#Fehlerstruktur

Ablehnungen auf Gateway-Seite nutzen die Fehlerstruktur im OpenAI-Format mit type "xiaoxiang_error". Upstream-Fehler werden unverändert weitergeleitet, asynchrone Task-Endpunkte antworten mit einem flachen Body, und zwei Fälle haben gar keinen Body — lesen Sie die Fehlerseite, bevor Sie Ihren Parser schreiben.

error.json

HTTP/1.1 402 Payment Required
X-Oneapi-Request-Id: 2026091023...

{
  "error": {
    "message": "insufficient account balance, please top up to continue (request id: 2026091023...)",
    "type": "xiaoxiang_error",
    "code": "insufficient_user_quota"
  }
}

Alle fünf Fehlerstrukturen und die Fehlercode-Tabelle →

#Wiederholungsstrategie

Wiederholen Sie 429 und 5xx mit exponentiellem Backoff und beachten Sie Retry-After, falls vorhanden. Wiederholen Sie keine 4xx-Validierungsfehler — derselbe Body schlägt wieder fehl. Senden Sie bei kostenpflichtigen Einreichungen einen Idempotency-Key, damit eine Wiederholung nach einem Timeout das erste Ergebnis erneut liefert, statt einen zweiten Job zu starten.

backoff.py

import time, requests

def call_with_backoff(url, headers, body, tries=5):
    for i in range(tries):
        r = requests.post(url, headers=headers, json=body)
        if r.status_code not in (429, 500, 502, 503, 504):
            return r
        # 429 and 413 have no JSON body — never parse before checking status.
        wait = int(r.headers.get("Retry-After", 2 ** i))
        time.sleep(wait)
    r.raise_for_status()

So funktionieren Idempotenzschlüssel →

#Maschinenlesbare Spezifikation

Derselbe Vertrag in zwei generierten Formaten: OpenAPI für Client-Generierung, Postman und API-Tools sowie eine einzelne Markdown-Datei zum Einfügen in einen Coding-Agent. Beide werden aus diesen Seiten neu erzeugt und können daher nicht von dem abweichen, was Sie hier lesen.

openapi.json

OpenAPI 3.1 — jeder dokumentierte Pfad mit seinen Parametern und Fehlerantworten.

llms-full.txt

Der gesamte Wire-Vertrag als eine Markdown-Datei, passend für das Kontextfenster eines Agents.

llms.txt

Kurzer Index aller Doku-Seiten, für KI-Clients, die ihn zuerst abrufen.

Die Server-URL wird auf diese Domain umgeschrieben, generierte Clients brauchen also keine zusätzliche Konfiguration.

generate-a-client.sh

# Any OpenAPI generator works; this is the common one.
npx @openapitools/openapi-generator-cli generate \
  -i https://www.aisplice.store/openapi.json \
  -g python \
  -o ./gateway-client

#Endpunkte im Überblick

Jeder Pfad akzeptiert den OpenAI-Anfrage-Body — anbieterspezifische Parameter (anthropic tool_use, gemini thinking_config) werden unverändert durchgereicht. Anbieter-native und eingefrorene Legacy-Routen sind separat auf der Kompatibilitätsseite aufgeführt.

Text
POST	/v1/chat/completions	Chat über mehrere Runden, Tool-Calling, Streaming, JSON-Modus.
POST	/v1/responses	Einzelne Textantwort mit strukturierten Ausgaben und Reasoning.
POST	/v1/messages	Anthropic-natives Format — gleiche Authentifizierung, kein Adapter nötig.
POST	/v1/responses/compact	Ein langes Gespräch bei Modellen komprimieren, die Compaction unterstützen — ohne Streaming-Variante.
Vektor
POST	/v1/moderations	Inhaltsmoderation im selben Wire-Format.
Musik
POST	/v1/music/generations	Asynchrone Musikgenerierung — gibt eine task_id zurück; optionaler Webhook wird unterstützt.
GET	/v1/music/tasks/:task_id	Status und Fortschritt asynchroner Musik-Tasks abfragen.
GET	/v1/music/tasks/:task_id/content	Das fertige Audio über das Gateway abrufen.
Bild
POST	/v1/images/tasks	Asynchrone Bildgenerierung, die Route der Bildmodelle — gibt eine task_id zurück; optionaler Webhook wird unterstützt.
GET	/v1/images/tasks/:task_id	Status und Fortschritt asynchroner Bild-Tasks abfragen.
GET	/v1/images/tasks/:task_id/content	Endgültige Bild-URLs abrufen — dauerhafte Links, sicher speicherbar.
Video
POST	/v1/videos	Videogenerierung im OpenAI-Format (Sora, Doubao) — optionaler Webhook wird unterstützt.
GET	/v1/videos/:task_id	Status asynchroner Tasks abfragen; der Inhalt liegt unter /content.
GET	/v1/videos/:task_id/content	Das fertige Video über das Gateway herunterladen.
DELETE	/v1/videos/:task_id	Einen Task abbrechen, der noch keinen Endzustand erreicht hat.
POST	/v1/videos/:video_id/remix	Ein vorhandenes Video mit neuem Prompt neu rendern, bei Modellen, die das unterstützen.
3D
POST	/v1/model3d/tasks	Asynchrone 3D-Asset-Generierung und Nachbearbeitung — gibt eine task_id zurück.
GET	/v1/model3d/tasks/:task_id	Den 3D-Task abfragen; die Ergebnis-URL steht im Task-Body, eine /content-Route gibt es nicht.
Medien
POST	/v1/media/upload-policy	Eine kurzlebige Upload-Policy für ein Bild, Video, Audio oder eine sonstige Datei bis zum konfigurierten Limit erstellen.
App-Abos
POST	/v1/google-play/verify	Ein Google-Play-Kauftoken mit dem für diesen Schlüssel hinterlegten Dienstkonto gegen Ihre App prüfen — kostenlos, kein Modellaufruf.
POST	/v1/xsolla/verify	Prüft mit dem Xsolla-API-Schlüssel dieses Schlüssels, ob ein Xsolla-Nutzer ein aktives Abo hat — kostenlos, kein Modellaufruf.
Konto
GET	/v1/balance	Kontoguthaben und das, was dieser Schlüssel noch ausgeben kann — kostenlos, kein Modellaufruf.
Metadaten
GET	/v1/models	Alle Modelle auflisten, die dieser Schlüssel nutzen darf.
GET	/v1/models/:model	Einen einzelnen Modelleintrag abrufen — das Format, das Anthropic- und OpenAI-Clients beim Start abfragen.

Immer noch nicht gelöst?

Senden Sie uns die Anfrage-ID oder die Fehlermeldung, und wir sehen uns das an.

ZurückDateien hochladen WeiterAsynchrone Tasks