AI Gateway

Verwenden Sie die AI -Konten, die mit Ihrer eigenen AirCode Ø -Instanz aus Ihren persönlichen Anwendungen verbunden sind. Versorgen Sie Ihre Instanz mit der -Basis URL, einem separaten -Anwendungstokenund einem exakten -Modell ID. Die Instanz ruft ihren angeschlossenen Anbieter CLI auf und gibt die Antwort über einen Untersatz Chat Completions für Text und einen Untersatz Bilder für Bilder zurück.

Your application's backend
  → your instance URL + application token
    → a connected native provider account
      → validated answer + available usage counters

Die Website beherbergt nur Dokumentation. API -Anfragen gehen direkt zu Ihrer Instanz; aircodezero.com erhält keine Instanzadresse, Token oder Anweisungen. Nutzen Sie diesen Service nur für Ihre eigenen Anwendungen und Konten. Anbieterbedingungen, Abonnementzugang und Quoten gelten weiterhin.

Instanz einrichten

1. Verbinden Sie ein kompatibles natives Anbieterkonto in AI Verwendung. Das Gateway listet die von der installierten Instanz unterstützten Konto-Modelle auf; API-key und verwaltete Kreditverbindungen sind ausgeschlossen.
2. Öffnen Sie Einstellungen → AI-Gateway auf dem Desktop oder im Web, auf Mobilgeräten Mehr → AI-Gateway. Aktivieren Sie unter Zugriff erstellen die Option Private Verbindungen erlauben.
3. Kopieren Sie die angezeigte Base URL. Es endet in /api/ai-gateway/v1.
4. Wählen Sie unter Token erstellen die Option Eine Anwendung, geben Sie ihren Namen ein und wählen Sie Token erstellen. Kopieren Sie das einmal angezeigte Token. Diese Wahl erlaubt Text- und Bildzugriff über die KI-API, aber keine Sitzungen zwischen Instanzen.
5. Konfigurieren Sie diese Server-Seite-Umweltvariablen in Ihrer Anwendung:

Bewahren Sie Token in der geheimen Konfiguration Ihres Backends auf, nicht in Browser-Code, einem Mobile-App-Bundle, einem Repository, einem URL oder einer geteilten Konversation. Die Beispiele lesen Umgebungsvariablen anstelle von Einbettungsanweisungen. Verwenden Sie niemals das Instanz-Passwort oder ein Eigentümer-Login-Token im Feld API-key.

Die Instanz muss ausgeführt und aus dem Backend Ihrer Anwendung erreichbar bleiben. localhost bedeutet den Computer, auf dem dieses Backend ausgeführt wird. Verwenden Sie die HTTPS -Adresse der Instanz für den Remote-Zugriff oder Ihre vertrauenswürdige lokale/private Netzwerkverbindung. Das Gateway schafft keine öffentliche Herkunft. Ein Anbieter, der nicht von /models aufgeführt ist, kann nicht durch die Erfindung eines ID ausgewählt werden.

Authentifizierung und Modellfindung

Senden Sie Authorization: Bearer YOUR_APPLICATION_TOKEN bei jedem Anruf. Senden Sie JSON mit Content-Type: application/json. Keine Abfrageparameter oder Cookie-Authentifizierung werden unterstützt. Cross-origin-Browseranrufe werden nicht unterstützt; Verwenden Sie Ihr Backend.

GET {BASE_URL}/models gibt ein Objekt mit object: "list" und einem data -Array zurück. Jedes Modell bietet eine id Die Ausstellung label, engine, engineLabel, provider, connectionLabel, efforts und capabilities: chat.completions für Textmodelle, images.generations und images.edits für das Bildmodell. Pass die zurückgegebene id unverändert; es kann bereits Prozentsatz-Codierung enthalten. Die Liste kann sich ändern, wenn sich Konten, Anbieterzugriff oder installierte Modelle ändern.

Für die Konfiguration einer OpenAI-kompatiblen Anwendung wählen Sie Chat Completions, verwenden Sie die vollständige Basis URL, legen Sie den Anwendungs-Token in sein API -Schlüsselfeld und kopieren Sie eine der zurückgegebenen Modell-IDs. Images verwendet die unten beschriebenen Images-Subsets. Eine Anwendung, die Antworten, Tools oder nicht unterstützte Sampling-Parameter erfordert, ist nicht mit dem aktuellen Gateway kompatibel.

Erstellen einer Antwort

POST {BASE_URL}/chat/completions akzeptiert die folgenden Felder. Unbekannte Felder werden eher abgelehnt als stillschweigend ignoriert.

Nachrichten enthalten nur role und content. Textblöcke werden mit Newlines verbunden. Null Charaktere werden abgelehnt. Die normalisierte Message-Array muss innerhalb von 64 KiB von UTF-8 JSON passen; der gesamte HTTP -Körper ist auf 80 KiB begrenzt. Die validierte Antwort ist auf 49,152 JavaScript-Stringcode-Einheiten beschränkt. Dies sind Gateway-Limits, keine Versprechungen bezüglich des Kontextfensters oder der Ausgangskapazität eines Anbieters.

Bereitstellen Sie das vollständige relevante Gespräch bei jedem Anruf. Um eine Konversation fortzusetzen, fügen Sie die vorherige Antwort des Assistenten und die nächste Benutzernachricht hinzu. Das Gateway erstellt oder speichert keine Konversation, Sitzung oder Abschlussverlauf. Ein Token gewährt keinen Zugriff auf Instanzenprojekte, Dateien, Terminals, Sitzungen oder Eigentümereinstellungen.

Eine normale Antwort hat object: "chat.completion"; Lesen Sie den Text von choices[0].message.content. Es enthält auch id, created, die angeforderte modelund finish_reason: "stop". Native Zähler erscheinen in usage , wenn sie vollständig genug sind, um zu berichten. Die Erweiterung aircode_usage speichert Buchhaltungsdetails und unvollständige Schätzungen. Fehlende Zähler oder Preise sind unbekannt, nie Null. API-äquivalent Schätzungen sind keine zusätzlichen Abonnementgebühren.

Streaming

Setzen Sie stream: true auf Content-Type: text/event-stream. Die aktuelle Implementierung verwendet buffered streaming: es sendet einen ersten wartenden Kommentar und keepalive Kommentare, während der Anbieter läuft, dann sendet die vollständige Antwort nach der Validierung. Es nicht Stream Wörter oder Token, wie sie generiert werden.

Ein erfolgreicher Stream enthält:

1. SSE Kommentare, die mit : beginnen, während Sie warten; ignorieren Sie sie.
2. Ein data: JSON chat.completion.chunk mit der Assistentenrolle und vollständig Text in choices[0].delta.content.
3. Ein Stück mit einem leeren Delta und finish_reason: "stop".
4. Ein optionales Stück mit choices: [], usage (möglicherweise null) und aircode_usage wenn stream_options.include_usage wahr ist.
5. data: [DONE].

Nachdem ein Stream begonnen hat, kommen Fehler als ein SSE data: -Ereignis mit error; behandeln Sie HTTP 200 nicht allein als Erfolg. Ein gescheiterter Strom schließt ohne den Erfolgsmarkierer. SSE Frames können über Transport-Stücke aufgeteilt werden; Verwenden Sie einen SDK oder einen SSE Parser, anstatt jeden Netzwerk-Stücke als JSON zu parsen.

Wenn Sie eine Verbindung schließen, wird die aktive Anfrage storniert. Wenn Sie ein Token widerrufen, das Gateway deaktivieren oder die Instanz stoppen, wird auch die entsprechende Arbeit storniert. Es gibt keine automatische Wiedergabe oder Wiederholung. Langlaufende Anfragen benötigen einen geeigneten Client und einen reverse-proxy-Timing; Keepalives können die absolute Anfrage-Dauer-Limite eines Netzwerks nicht übertreffen.

Bild erzeugen

Das Bildmodell wird aufgelistet, während das native Codex -Konto der Instanz sein eigenes Bildwerkzeug verwenden kann, das einen ChatGPT-Plan erfordert, der die Bildgenerierung beinhaltet. Seine id ist codex/image-generation. Codex entscheidet, welches Bildmodell es verwendet; das Gateway wählt es nicht.

• POST {BASE_URL}/images/generations nimmt JSON mit model, prompt (bis zu 32.000 Zeichen) und optional size, n: 1 und response_format: "b64_json".
• POST {BASE_URL}/images/edits nimmt multipart/form-data mit den gleichen Feldern und 1 bis 4 Referenzbilder in image oder image[]. Jeder muss ein PNG oder JPEG von maximal 4 MiB. Andere Dateifelder, wie z.B. mask, werden abgelehnt.

size ist auto oder WIDTHxHEIGHT zwischen 64 und 4096 Pixel. Es wird als Leitfaden an das Modell weitergegeben; die Antwort berichtet über die tatsächliche Größe. Alle anderen Felder werden abgelehnt, anstatt ignoriert.

curl -sS "$AIRCODE_AI_BASE_URL/images/edits" \
  -H "Authorization: Bearer $AIRCODE_AI_TOKEN" \
  -F model=codex/image-generation \
  -F "prompt=Place this product in a premium studio shot on a stone pedestal." \
  -F size=1024x1536 \
  -F image=@product.png

Eine Antwort trägt created, eine data[0].b64_json, output_format (png, jpeg oder webp), die tatsächlichen size und aircode_usage. Die Buchhaltung deckt den Agent ab, der das Bildwerkzeug angetrieben hat; der Anbieter berichtet nicht über die Kosten des Bildwerkzeugs selbst, so dass costComplete immer false ist. Eine Generation dauert in der Regel ein bis drei Minuten, teilt die Grenzen unten mit Textanrufen und wird storniert, wenn der Client die Verbindung trennt. Wenn das Modell ohne ein Bild antwortet, scheitert der Anruf mit 422 AI_GATEWAY_NO_IMAGE und dem Satz des Modells, wenn er einen gegeben hat.

Automatische Verbindung einer gespeicherten AirCode Ø -App

Eine in Apps gespeicherte App, die ihren eigenen Server ausführt, kann diesen Zugriff erhalten, ohne einen Token zu kopieren. Öffnen Sie auf der Seite der App Einstellungen → Zugriff → AI Konten und schalten Sie es ein. AirCode Ø dann:

1. Schaltet das private AI -Gateway ein, wenn es ausgeschaltet war;
2. Die App neu startet und bei jedem Start seinen Server ein frisches Token seiner eigenes, das Token des vorherigen Starts widerrufen;
3. Setzt AIRCODE_AI_BASE_URL (das Gateway auf der Adresse, auf der die Instanz hört), AIRCODE_AI_TOKEN und, wenn verfügbar, AIRCODE_AI_MODEL (ein Textmodell) und AIRCODE_AI_IMAGE_MODEL (das Bildmodell).

Eine veröffentlichte Version der App erhält auf die gleiche Weise ihr eigenes Token. Wenn Sie AI -Konten ausschalten, werden die Token der App sofort widerrufen. Rufen Sie das Gateway vom Server der App an und bewahren Sie das Token dort auf: Jeder, der die App öffnen kann, kann Ihre Konten über sie nutzen, und ihre Verwendung zählt zu Ihren Plänen.

Quoten, Token-Lebenszyklus und Fehler

Das Gateway ermöglicht zwei aktive Anrufe pro Instance, einen aktiven Anruf pro Token und 30 zugelassene Generationsanfragen pro Token pro Minute. Anrufe werden nicht gehalten. Diese lokalen Grenzwerte ersetzen die Anbieterquoten nicht. Token verfallen nach 90 Tagen; Erstellen Sie einen Ersatz, aktualisieren Sie Ihre Anwendung und widerrufen Sie dann den vorherigen Token. Das Deaktivieren des Gateways behält Token, suspendiert aber deren Verwendung. Die Wiederherstellung des Instance-Status deaktiviert das Gateway und löscht die Token-Autorität; Erstellen Sie frische Token.

Fehler verwenden error.message, error.type, error.code und error.param. Lesen Sie den Code sowie den HTTP -Status. Vermeiden Sie eine Generation, deren Ergebnis unbekannt ist: Sie hat möglicherweise bereits Lieferantenquoten verbraucht. Die Beispiele deaktivieren SDK Retries.

Eine unbekannte Anbieter-Reset-Zeit bleibt unbekannt. Starten Sie niemals einen von einem Modellnamen oder dem Quotenplan eines unabhängigen Anbieters.

Verwendung einer anderen Instanz aus der Anwendung

Eine externe Anwendung kann eine andere eigene Instanz mit deren Base URL und einem dort erstellten Token aufrufen. Jeder Token gehört zu seiner ausstellenden Instanz. Soll ein Agent auf B am Projekt von A arbeiten, wählen Sie beim Erstellen des Tokens auf B Andere Instanz und folgen Sie Remote Sessions. Standardmäßig bleiben Dateien und Befehle auf A. Speichern Sie die Verbindung auf A, wählen Sie B unter Neue Sitzung → Ausführen auf und lassen Sie Projektort → Diese Instanz ausgewählt. Für ein Projekt auf B wählen Sie beim Erstellen des Tokens dort Diese Instanz und das Projekt; beim Start auf A wählen Sie Projektort → Remote-Instanz. Beide Wege liefern Live-Ereignisse. Normale Token decken Text und Bilder ab, melden den Client aber nicht als entfernten Eigentümer an. Werkzeugaufrufe über Responses, Anthropic Messages und Chat Completions gehören nicht zum unterstützten Umfang der Text-API.

Für die AI-assistierte Integration siehe -Dokumentation für AI, die Roh- Markdown -Anleitung, die OpenAPI -Schemaund die -Integrationsfähigkeit.

Codebeispiele

Legen Sie die drei Umweltvariablen oben fest, bevor Sie ein Beispiel ausführen. Diese Snippets sind auch in den Einstellungen und in der Roh Markdown-Anleitung verfügbar.

set -euo pipefail
# The token is read from standard input, not a command-line argument.
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/models" --header @- <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

body=$(jq -n --arg model "$AIRCODE_AI_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello!"}]}')
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/chat/completions" \
  --header 'Content-Type: application/json' \
  --header @- --data "$body" <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

import os
from openai import OpenAI, DefaultHttpx2Client

client = OpenAI(
    base_url=os.environ["AIRCODE_AI_BASE_URL"],
    api_key=os.environ["AIRCODE_AI_TOKEN"],
    max_retries=0,
    http_client=DefaultHttpx2Client(follow_redirects=False),
)

for model in client.models.list():
    print(model.id)

response = client.chat.completions.create(
    model=os.environ["AIRCODE_AI_MODEL"],
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

function required(name) {
  if (!process.env[name]) throw new Error("Set " + name + " first.");
  return process.env[name];
}

const client = new OpenAI({
  baseURL: required("AIRCODE_AI_BASE_URL"),
  apiKey: required("AIRCODE_AI_TOKEN"),
  maxRetries: 0,
  fetchOptions: { redirect: "error" },
});

const stream = await client.chat.completions.create({
  model: required("AIRCODE_AI_MODEL"),
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
  stream_options: { include_usage: true },
});

try {
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
    if (chunk.usage) console.error("Tokens:", chunk.usage.total_tokens);
  }
  process.stdout.write("\n");
} finally {
  stream.controller.abort();
}

SDK Konfiguration Referenzen:OpenAI Python-SDK für den Computerund OpenAI JavaScript SDK. Dieses Gateway unterstützt das oben dokumentierte Subset.