API-Schlüssel

Nur für Administratoren

Diese Einstellung ist nur für Benutzer mit der Rolle Administrator sichtbar.

Über die Ayunis-API können Sie die Sprachmodelle Ihrer Organisation auch außerhalb der gewohnten Web-Oberfläche nutzen – zum Beispiel direkt aus einem Fachverfahren, einem internen Portal oder einem Automatisierungs-Workflow heraus. Damit eine externe Anwendung sich gegenüber Ayunis ausweisen darf, benötigt sie einen API-Schlüssel. Sie als Administrator erstellen diesen Schlüssel und geben ihn auf sicherem Weg an die zuständige Stelle weiter – in der Regel an Ihre IT-Abteilung, Ihren IT-Dienstleister oder den Hersteller des angebundenen Systems.

Wofür ist die API gedacht?

Typische Einsatzszenarien in der Verwaltung sind:

• Anbindung an Fachverfahren – z. B. damit Ihr Dokumentenmanagement-System eingehende Schreiben automatisch zusammenfasst, klassifiziert oder mit Schlagwörtern versieht.
• Automatisierung wiederkehrender Aufgaben – etwa das automatische Übersetzen oder Vorprüfen großer Mengen von Dokumenten in einem internen Skript.
• Integration in eigene Anwendungen – wenn Sie Ayunis-Funktionen in einem internen Mitarbeiterportal oder einer eigenen Web-Anwendung anbieten möchten.
• Workflows mit Automatisierungstools – z. B. mit Tools wie n8n, Make oder eigenen Python-Skripten, um wiederkehrende Abläufe zu automatisieren.

Sie selbst müssen nicht programmieren

Die API wird üblicherweise von Ihrer IT-Abteilung, einem IT-Dienstleister oder dem Hersteller Ihres Fachverfahrens genutzt. Ihre Aufgabe als Administrator ist es, den Zugang zu erstellen, sicher weiterzugeben und bei Bedarf wieder zu widerrufen.

Voraussetzungen

Damit die API genutzt werden kann, müssen folgende Punkte erfüllt sein:

1. Ein API-Schlüssel – wird in dieser Einstellung erstellt.
2. Ein nutzungsbasiertes Abonnement (oder verbleibende Test-Nachrichten) für Ihre Organisation.
3. Mindestens ein aktiviertes Modell unter Admin-Einstellungen → Modelle.

API-Schlüssel-Einstellungen öffnen

1. Navigieren Sie zu Admin-Einstellungen → API-Schlüssel
2. Sie sehen eine Liste aller API-Schlüssel Ihrer Organisation

API-Schlüssel erstellen

1. Klicken Sie auf API-Schlüssel erstellen
2. Geben Sie einen Namen für den Schlüssel ein (z. B. „DMS-Anbindung Bauamt” oder „Übersetzungs-Skript Sozialamt”) – damit erkennen Sie später leicht, wofür der Schlüssel verwendet wird.
3. Optional: Wählen Sie ein Ablaufdatum – nach diesem Datum funktioniert der Schlüssel nicht mehr. Leer lassen für einen Schlüssel, der nie abläuft.
4. Klicken Sie auf Schlüssel erstellen

Nach der Erstellung wird der vollständige API-Schlüssel einmalig angezeigt. Kopieren Sie ihn sofort und geben Sie ihn auf sicherem Weg an die Person oder das System weiter, das ihn verwenden soll – z. B. über einen Passwort-Manager Ihrer Organisation.

Schlüssel sofort speichern

Der vollständige API-Schlüssel wird nur einmal bei der Erstellung angezeigt. Nachdem Sie den Dialog geschlossen haben, kann er nicht mehr abgerufen werden. Wenn Sie den Schlüssel verlieren, müssen Sie einen neuen erstellen.

Die Schlüssel-Liste verstehen

Jeder API-Schlüssel in der Liste zeigt:

• Name – der bei der Erstellung vergebene Name
• Schlüssel-Präfix – eine kurze Vorschau des Schlüssels (z. B. ayu_abc1...) zur Identifikation
• Erstellt am – wann der Schlüssel erstellt wurde
• Ablauf – wann der Schlüssel abläuft, oder „Läuft nie ab”
• Status – ob der Schlüssel aktiv ist oder widerrufen wurde

API-Schlüssel widerrufen

Wenn ein Schlüssel nicht mehr benötigt wird, ein Dienstleister wechselt oder der Schlüssel versehentlich an die falsche Stelle gelangt ist, können Sie ihn jederzeit widerrufen:

1. Finden Sie den Schlüssel in der Liste
2. Klicken Sie auf die Widerrufen-Schaltfläche (Papierkorb-Symbol)
3. Bestätigen Sie die Aktion im Dialog

Sofortige Wirkung

Das Widerrufen eines Schlüssels wird sofort wirksam. Alle Anwendungen oder Tools, die diesen Schlüssel verwenden, funktionieren sofort nicht mehr. Diese Aktion kann nicht rückgängig gemacht werden.

Credit-Limit für einen API-Schlüssel festlegen

Sie können ein monatliches Credit-Limit für einzelne API-Schlüssel festlegen, um zu steuern, wie viele Credits über einen bestimmten Schlüssel pro Kalendermonat verbraucht werden dürfen. Das ist besonders nützlich, wenn Sie verschiedene Schlüssel an verschiedene Systeme oder Dienstleister vergeben und den Verbrauch pro Anbindung kontrollieren möchten.

Credit-Limit setzen oder bearbeiten

1. Finden Sie den API-Schlüssel in der Liste
2. Klicken Sie auf die drei Punkte neben dem Schlüssel
3. Wählen Sie Credit-Limit festlegen (oder Credit-Limit bearbeiten, wenn bereits eines gesetzt ist)
4. Geben Sie die Anzahl der monatlichen Credits ein
5. Klicken Sie auf Limit speichern

Die Schlüssel-Liste zeigt den aktuellen Verbrauch im Verhältnis zum Limit an (z. B. „120 von 500 Credits in diesem Monat verbraucht”). Schlüssel ohne Limit zeigen „Kein Credit-Limit” an.

Credit-Limit entfernen

1. Klicken Sie auf die drei Punkte neben dem Schlüssel
2. Wählen Sie Credit-Limit entfernen

Ohne Credit-Limit kann der Schlüssel Credits frei innerhalb des Gesamtbudgets der Organisation nutzen.

Hinweis

Wenn Sie das Credit-Limit auf 0 setzen, wird die Nutzung kostenpflichtiger Modelle über diesen Schlüssel pausiert. API-Anfragen, die das Limit überschreiten würden, werden abgelehnt.

Best Practices für sichere API-Schlüssel

• Aussagekräftige Namen verwenden – benennen Sie Schlüssel nach ihrem Verwendungszweck oder dem System, das sie nutzt (z. B. „DMS-Anbindung”, „Ratsinfo-Workflow”).
• Ein Schlüssel pro Anwendung oder Dienstleister – nutzen Sie für jede Anwendung und jeden Dienstleister einen eigenen Schlüssel. So können Sie den Zugang einzeln widerrufen, ohne andere Anbindungen zu beeinträchtigen.
• Ablaufdaten setzen – für temporäre Integrationen oder externe Dienstleister ein Ablaufdatum setzen, damit der Schlüssel automatisch ungültig wird.
• Schlüssel regelmäßig rotieren – erstellen Sie regelmäßig neue Schlüssel und widerrufen Sie alte.
• Sicher weitergeben – geben Sie Schlüssel nur über vertrauenswürdige Wege weiter (z. B. Passwort-Manager). Versenden Sie sie nicht per E-Mail oder Chat.

Technische Schnittstelle

Hinweis für die IT

Dieser Abschnitt richtet sich an die IT-Abteilung oder den Dienstleister, der die Anbindung umsetzt. Als Administrator können Sie ihn direkt weiterleiten – Sie müssen die folgenden Schritte nicht selbst durchführen.

Ayunis bietet eine OpenAI-kompatible API. Damit lassen sich die offiziellen OpenAI-Bibliotheken (Python, Node.js) und beliebige HTTP-Clients verwenden – es muss lediglich die Basis-URL angepasst werden.

Basis-URL

https://core.ayunis.com/api/openai-compat/v1

Authentifizierung

Alle Anfragen werden mit dem API-Schlüssel im Authorization-Header authentifiziert:

Authorization: Bearer ayu_ihr-api-schluessel

Endpunkt: Chat Completions

POST /api/openai-compat/v1/chat/completions

Anfrage-Beispiel

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "Du bist ein hilfreicher Assistent." },
    { "role": "user", "content": "Was ist die Hauptstadt von Frankreich?" }
  ],
  "stream": false
}

Den Wert für model finden Sie in Admin-Einstellungen → Modelle – er steht jeweils unter dem Anzeigenamen des Modells.

Wichtige Parameter

Parameter	Typ	Erforderlich	Beschreibung
model	string	Ja	Technischer Modell-Bezeichner aus den Modell-Einstellungen.
messages	array	Ja	Konversationsverlauf, jeweils mit role (system, user, assistant) und content.
stream	boolean	Nein	Auf true setzen, um die Antwort als Server-Sent-Events-Stream zu erhalten.
temperature	number	Nein	Steuert die Zufälligkeit (0–2). Niedrigere Werte erzeugen fokussiertere Antworten.
max_tokens	number	Nein	Maximale Anzahl der zu generierenden Tokens.
tools	array	Nein	Liste von Tool-/Funktionsdefinitionen, die das Modell aufrufen kann.
tool_choice	string	Nein	Steuert, ob das Modell Tools verwenden soll (auto, none oder ein bestimmter Funktionsname).

Dokumente inline senden

Sie können Dokumente direkt in der Nachricht mitsenden, ohne sie vorher separat hochzuladen. Fügen Sie dazu ein Element vom Typ file in das content-Array einer Nachricht ein. Die Datei wird als Base64-codierter String übergeben:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Fasse dieses Dokument zusammen." },
    {
      "type": "file",
      "file": {
        "filename": "bericht.pdf",
        "file_data": "data:application/pdf;base64,JVBERi0xLjQg..."
      }
    }
  ]
}

Einschränkungen:

• Maximal 5 Dateien pro Anfrage
• Maximale Gesamtgröße aller Dateien: 3 MB
• Unterstützte Formate: PDF, Word, PowerPoint, Text-Dateien

Beispiele mit dem OpenAI-SDK

Python

from openai import OpenAI

client = OpenAI(
    api_key="ayu_ihr-api-schluessel",
    base_url="https://core.ayunis.com/api/openai-compat/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hallo, wie können Sie mir helfen?"}
    ]
)

print(response.choices[0].message.content)

Node.js / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "ayu_ihr-api-schluessel",
  baseURL: "https://core.ayunis.com/api/openai-compat/v1"
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "user", content: "Hallo, wie können Sie mir helfen?" }
  ]
});

console.log(response.choices[0].message.content);

Endpunkt: Modelle auflisten

GET /api/openai-compat/v1/models

Gibt eine Liste aller Sprachmodelle zurück, die für Ihre Organisation aktiviert sind. Das ist nützlich, um Modellauswahlen in angebundenen Anwendungen automatisch zu befüllen oder um vor dem Senden einer Chat-Completion-Anfrage zu prüfen, welche Modelle verfügbar sind.

Einzelnes Modell abrufen

GET /api/openai-compat/v1/models/{model-id}

Gibt Details zu einem bestimmten Modell anhand seines technischen Bezeichners zurück.

Streaming

Für längere Antworten kann Streaming aktiviert werden, um Teilergebnisse zu erhalten, während sie generiert werden:

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Schreibe ein kurzes Gedicht."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Rate-Limits

Die API ist auf 60 Anfragen pro Minute pro Client-IP-Adresse begrenzt. Bei Überschreitung wird 429 Too Many Requests zurückgegeben.

Fehlerbehandlung

Fehler werden im Standard-OpenAI-Fehlerformat zurückgegeben:

{
  "error": {
    "message": "Beschreibung des Fehlers",
    "type": "error_type",
    "code": "error_code"
  }
}

Häufige HTTP-Status:

HTTP-Status	Bedeutung
401	Ungültiger oder fehlender API-Schlüssel
403	Kein aktives Abonnement oder Kontingent erschöpft
404	Modell nicht gefunden oder für die Organisation nicht freigegeben
429	Rate-Limit überschritten
500	Interner Serverfehler

Credit-Verbrauch

API-Anfragen verbrauchen Credits aus dem Kontingent Ihrer Organisation, genau wie Nachrichten über die Web-Oberfläche. Die Credit-Kosten hängen von der Nutzungsstufe des Modells und der Anzahl der verarbeiteten Tokens ab.

Nächste Schritte

• Modelle – Sehen, welche Modelle für die API verfügbar sind und wie ihre technischen Bezeichner lauten.
• Integrationen – Andere Systeme an Ayunis anbinden.