# Endpoints compatibles OpenAI

L’IA managée de KolWrite répond dans les mêmes formats que l’API OpenAI. Pointez un SDK
OpenAI, ou tout outil qui permet de définir une URL de base, vers KolWrite et utilisez un
token d’accès personnel comme clé d’API :

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

Les appels consomment les crédits du compte propriétaire du token, mesurés par token
d’utilisation. Ils sont distincts des jobs de transcription (voir le
[guide des agents](/locales/fr/agents.md)).

## Prérequis

- Le token a le scope `ai:use`. Le préréglage Automation de l’app ne l’inclut pas :
  cochez-le à la création du token.
- Le token a été créé depuis une session connectée de l’app KolWrite. Les anciens tokens
  non liés à un produit sont refusés avec `legal_product_required` : créez-en un nouveau.
- Le compte a accepté dans l’app l’information en vigueur sur l’IA de tiers. Tant que ce
  n’est pas fait, l’API répond HTTP 428 avec `legal_acceptance_required`.
- L’accès à l’API est activé pour le compte (Réglages → Compte → Accès à l’API).

## Endpoints

| Endpoint | Rôle |
|---|---|
| `GET /models` | Les modèles utilisables, avec `credit_pricing` pour chacun |
| `POST /chat/completions` | Complétions de chat, avec streaming (`"stream": true`) |
| `POST /responses` | L’API Responses |
| `POST /embeddings` | Embeddings |
| `POST /audio/transcriptions` | Texte d’un court clip vocal (`file` en multipart) |
| `POST /images/generations` | Génération d’images |

Les modèles portent des alias stables : `kw-auto` (choisit entre un modèle rapide et un
modèle plus puissant), `kw-fast` et `kw-pro`. `GET /models` fait foi pour ce qui est
disponible avec votre token ; chaque entrée indique `context_window` et la prise en charge
des outils, de la vision et de l’audio.

## 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
```

## Un court clip ou un enregistrement complet ?

`/audio/transcriptions` est une voie rapide pour les clips courts : une requête, une
réponse, aucun job. Elle ne produit ni étiquettes de locuteurs ni la transcription
enregistrée avec ses versions. Pour une réunion, un entretien ou un long fichier, envoyez
le média et créez un job de transcription : il renvoie horodatage des mots, locuteurs,
SRT et VTT.

Avec `want_words=true`, la réponse du clip contient aussi `words` sous la forme
`{w, start, end}`, en secondes depuis le début du clip.

## Ce qui diffère d’OpenAI

- Les noms de modèles sont des alias KolWrite, pas des noms de modèles OpenAI.
- Le token est un token d’accès personnel KolWrite, facturé en crédits KolWrite.
- `kw-max` n’est pas disponible avec des tokens d’API.
- Les erreurs utilisent `detail.code`, comme dans [erreurs](/locales/fr/errors.md).

## Questions

### Puis-je utiliser le SDK OpenAI avec KolWrite ?

Oui. Définissez l’URL de base sur `https://api.kolwrite.com/api/v1/ai/openai` et la clé
d’API sur un token KolWrite ayant le scope `ai:use`.

### Le streaming et les outils sont-ils pris en charge ?

Les complétions de chat se font en streaming avec `"stream": true`. `GET /models` indique,
pour chaque modèle, s’il prend en charge les outils, la vision et l’audio.

### Quel endpoint transcrit de l’audio ?

`POST /audio/transcriptions` pour les clips courts ; les jobs de transcription pour tout le reste.