# OpenAI-kompatible Endpunkte

Die verwaltete KI von KolWrite antwortet in denselben Formaten wie die OpenAI-API. Richten Sie
ein OpenAI-SDK oder ein beliebiges Werkzeug, in dem Sie eine Basis-URL setzen können, auf KolWrite
und verwenden Sie ein persönliches Zugriffstoken als API-Schlüssel:

```
Base URL: https://api.kolwrite.com/api/v1/ai/openai
API key:  your kol_... token (scope ai:use)
```

Aufrufe verbrauchen Credits des Kontos, dem das Token gehört, gemessen pro Token Nutzung. Sie sind
von Transkriptionsjobs getrennt (siehe den [Leitfaden für Agenten](/locales/de/agents.md)).

## Voraussetzungen

- Das Token hat den Bereich `ai:use`. Die Voreinstellung Automatisierung der App enthält ihn nicht,
  setzen Sie ihn also beim Erstellen des Tokens.
- Das Token wurde in einer angemeldeten Sitzung der KolWrite-App erstellt. Ältere Tokens ohne
  Produktbindung werden mit `legal_product_required` abgelehnt: Erstellen Sie ein neues.
- Das Konto hat in der App die aktuelle Offenlegung zu KI von Drittanbietern akzeptiert. Bis dahin
  antwortet die API mit HTTP 428 und `legal_acceptance_required`.
- Der API-Zugriff ist für das Konto freigeschaltet (Einstellungen → Konto → API-Zugriff).

## Endpunkte

| Endpunkt | Was er tut |
|---|---|
| `GET /models` | Die nutzbaren Modelle, mit `credit_pricing` je Modell |
| `POST /chat/completions` | Chat-Antworten, mit Streaming (`"stream": true`) |
| `POST /responses` | Die Responses-API |
| `POST /embeddings` | Embeddings |
| `POST /audio/transcriptions` | Text für einen kurzen Sprachclip (`file` als Multipart) |
| `POST /images/generations` | Bilderzeugung |

Modelle haben stabile Aliase: `kw-auto` (wählt zwischen einem schnellen und einem stärkeren
Modell), `kw-fast` und `kw-pro`. `GET /models` ist die maßgebliche Quelle dafür, was Ihr Token
nutzen kann; jeder Eintrag nennt `context_window` und ob Werkzeuge, Bildverarbeitung und Audio
unterstützt werden.

## Python

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kolwrite.com/api/v1/ai/openai",
    api_key=os.environ["KOLWRITE_TOKEN"],
)

reply = client.chat.completions.create(
    model="kw-auto",
    messages=[{"role": "user", "content": "Summarize this transcript in five bullets: ..."}],
)
print(reply.choices[0].message.content)

vectors = client.embeddings.create(model="kw-embedding", input=["first text", "second text"])
```

## JavaScript

```js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kolwrite.com/api/v1/ai/openai",
  apiKey: process.env.KOLWRITE_TOKEN,
});

const stream = await client.chat.completions.create({
  model: "kw-fast",
  messages: [{ role: "user", content: "Write a title for this meeting." }],
  stream: true,
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
```

## curl

```bash
curl https://api.kolwrite.com/api/v1/ai/openai/chat/completions \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "kw-auto", "messages": [{"role": "user", "content": "Hello"}]}'

curl https://api.kolwrite.com/api/v1/ai/openai/audio/transcriptions \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -F file=@clip.wav -F model=kw-fast -F language=auto
```

## Kurzer Clip oder ganze Aufnahme?

`/audio/transcriptions` ist ein schneller Weg für kurze Clips: eine Anfrage, eine Antwort, kein
Job. Er erzeugt weder Sprecherlabels noch das gespeicherte, versionierte Transkript. Für eine
Besprechung, ein Interview oder eine lange Datei laden Sie das Medium hoch und erstellen einen
Transkriptionsjob: Er liefert Wortzeiten, Sprecher, SRT und VTT.

Mit `want_words=true` enthält die Antwort für den Clip zusätzlich `words` als `{w, start, end}` in
Sekunden ab Clipbeginn.

## Was anders ist als bei OpenAI

- Die Modellnamen sind KolWrite-Aliase, keine OpenAI-Modellnamen.
- Das Token ist ein persönliches KolWrite-Zugriffstoken, abgerechnet in KolWrite-Credits.
- `kw-max` ist mit API-Tokens nicht verfügbar.
- Fehler nutzen `detail.code`, wie unter [Fehler](/locales/de/errors.md).

## Fragen

### Kann ich das OpenAI-SDK mit KolWrite verwenden?

Ja. Setzen Sie die Basis-URL auf `https://api.kolwrite.com/api/v1/ai/openai` und den API-Schlüssel auf
ein KolWrite-Token mit dem Bereich `ai:use`.

### Werden Streaming und Werkzeuge unterstützt?

Chat-Antworten werden mit `"stream": true` gestreamt. `GET /models` zeigt je Modell, ob es
Werkzeuge, Bildverarbeitung und Audio unterstützt.

### Welcher Endpunkt transkribiert Audio?

`POST /audio/transcriptions` für kurze Clips; Transkriptionsjobs für alles andere.