Dokumentation

yeos documentation.

REST-API

API-Referenz

Die yeos-API ermöglicht es dir, Dokumentenintelligenz in deine eigenen Anwendungen zu integrieren. Alle API-Endpunkte basieren auf REST und geben JSON-Antworten zurück.

Basis-URL

https://cloud.yeos.ai/api

Authentifizierung

Alle API-Anfragen erfordern einen API-Schlüssel. Füge deinen Schlüssel als Bearer-Token im Authorization-Header ein.

Authorization: Bearer yeos_your_api_key

Interaktive Dokumentation

Für die vollständige API-Referenz mit Anfrage-/Antwort-Schemata, Beispielen und interaktiven Tests besuche unsere OpenAPI-Dokumentation.

Interaktive Dokumentation ansehen
Berechtigungen (Scopes)

Verfügbare Bereiche

API-Schlüssel können auf bestimmte Berechtigungen beschränkt werden. Verwende Scopes, um zu begrenzen, was jeder Schlüssel tun kann.

Format: bereich:aktion

Verfügbare Bereiche

conversations – Zugriff auf Gespräche

documents – Zugriff auf Dateien und Dokumente

members – Verwaltung von Teammitgliedern

organization – Organisationseinstellungen

api-keys – Verwaltung von API-Schlüsseln

billing – Abrechnungsvorgänge

Verfügbare Aktionen

read – Ressourcen anzeigen und auflisten

write – Ressourcen erstellen und ändern

delete – Ressourcen entfernen

admin – Administrative Vorgänge

Beispiel-Scopes

conversations:readconversations:read – Gespräche lesen
documents:writedocuments:write – Dokumente hochladen
organization:adminorganization:admin – Vollständige Organisationskontrolle
members:adminmembers:admin – Arbeitsbereichsmitglieder verwalten

Code-Beispiele

Schnelle Beispiele, um dir den Einstieg in die API zu erleichtern.

Python

pip install requests

Eine Datei hochladen:

import requests

headers = {
    "Authorization": "Bearer yeos_your_api_key",
}

data = {
    "organization_id": "your_org_id",
    # Optional: include to upload into a workspace.
    "workspace_id": "your_workspace_id",
}

# Upload a file
with open("document.pdf", "rb") as f:
    files = {"file": f}
    response = requests.post(
        "https://cloud.yeos.ai/api/files",
        headers=headers,
        files=files,
        data=data,
    )
    print(response.json())

Eine Frage stellen:

import requests

response = requests.post(
    "https://cloud.yeos.ai/api/chat/completions",
    headers={
        "Authorization": "Bearer yeos_your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-4",
        "stream": False,
        "messages": [
            {"role": "user", "content": "What is the refund policy?"}
        ],
        "organization_id": "your_org_id",
        "workspace_id": "your_workspace_id",
    },
)
print(response.json())

JavaScript / Node.js

npm install node-fetch

Eine Datei hochladen:

const fetch = require('node-fetch');
const FormData = require('form-data');
const fs = require('fs');

const workspaceId = 'your_workspace_id';
const formData = new FormData();
const fileStream = fs.createReadStream('document.pdf');
formData.append('file', fileStream);
formData.append('organization_id', 'your_org_id');
formData.append('workspace_id', workspaceId);

const response = await fetch('https://cloud.yeos.ai/api/files', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer yeos_your_api_key',
  },
  body: formData,
});
const data = await response.json();
console.log(data);

Eine Frage stellen:

const response = await fetch(
  'https://cloud.yeos.ai/api/chat/completions',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer yeos_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-4',
      stream: false,
      messages: [
        { role: 'user', content: 'What is the refund policy?' },
      ],
      organization_id: 'your_org_id',
      workspace_id: 'your_workspace_id',
    }),
  }
);
const data = await response.json();
console.log(data);
LIMITS UND MEHRVERBRAUCH

Tägliche Nachrichtenlimits

Jeder Tarif enthält ein tägliches Nachrichtenkontingent. Anfragen darüber hinaus werden mit HTTP 402 abgelehnt, sofern deine Organisation den kostenpflichtigen API-Mehrverbrauch nicht aktiviert hat.

Was ein 402 bedeutet

limit_reached – das inkludierte Tageskontingent ist aufgebraucht und Mehrverbrauch ist nicht aktiviert. Warte auf das Zurücksetzen des Kontingents oder aktiviere den Mehrverbrauch.

payment_required – Mehrverbrauch ist aktiviert, aber es liegt kein zahlungsfähiges Abonnement vor. Prüfe deine Zahlungsangaben.

overage_cap_exceeded – das Ausgabenlimit dieser Abrechnungsperiode ist erreicht. Ein Admin kann es in den Organisationseinstellungen erhöhen.

Kostenpflichtiger Mehrverbrauch

Ein Organisations-Admin kann den kostenpflichtigen API-Mehrverbrauch unter Organisationseinstellungen, Abonnement aktivieren. Zugriffe über API-Schlüssel laufen dann über das Tageskontingent hinaus weiter und werden nach gemessenem Tokenverbrauch abgerechnet. Anfragen aus der Web-App stoppen weiterhin am inkludierten Limit.

Der Mehrverbrauch wird pro Token abgerechnet: CHF 0.60 pro Million eingehender Tokens und CHF 2.25 pro Million ausgehender Tokens.

Ausgabenlimit

Der Mehrverbrauch ist durch ein Ausgabenlimit pro Periode begrenzt, damit eine aktivierte Organisation nie unbegrenzte Kosten verursacht. Admins können es anpassen; der aktuelle Verbrauch gegenüber dem Limit wird in den Organisationseinstellungen angezeigt.

Verbrauch nachvollziehen

Antworten der Chat-Completions enthalten ein OpenAI-kompatibles usage-Objekt mit Prompt-, Completion- und Gesamt-Tokenzahlen, damit du Kosten pro Anfrage zuordnen kannst.

Der Mehrverbrauch erscheint auf der nächsten Rechnung zusammen mit der Tarifgebühr – als separate Positionen in einer einzigen Belastung. Eine Periode wird nach ihrem Ende abgerechnet.

Der Free-Tarif hat vollen API-Zugriff, kann aber keinen kostenpflichtigen Mehrverbrauch aktivieren und stoppt immer am inkludierten Tageskontingent.

Häufige Fragen

Wie erhalte ich einen API-Schlüssel?

API-Schlüssel werden in deinen Organisationseinstellungen erstellt. Nur Organisationsinhaber und Admins können API-Schlüssel erstellen und verwalten.

Was ist das Rate-Limit?

Rate-Limits hängen von deinem Plan ab. Der kostenlose Plan hat grundlegende Limits, während kostenpflichtige Pläne höhere Rate-Limits für die Produktion bieten.

Kann ich die API ohne Organisation nutzen?

Nein. Alle API-Anfragen sind auf eine Organisation bezogen. Du musst zuerst eine Organisation erstellen.

Werden API-Antworten gestreamt?

Ja. Das Beantworten von Fragen unterstützt Server-Sent Events (SSE) für Streaming-Antworten. Prüfe die OpenAPI-Dokumentation für die aktuellen Streaming-Endpunkt-Details.

Wie gehe ich mit Fehlern um?

Die API gibt standardmässige HTTP-Statuscodes zurück. 4xx-Fehler weisen auf Client-Probleme hin (fehlerhafte Anfrage, nicht autorisiert), während 5xx-Fehler auf Server-Probleme hinweisen. Prüfe den Antwortkörper für Fehlerdetails.