# Endpoint compatibili con OpenAI

L’IA gestita di KolWrite risponde negli stessi formati dell’API di OpenAI. Punta un SDK di
OpenAI, o qualsiasi strumento in cui si possa impostare un URL di base, su KolWrite e usa
un token di accesso personale come chiave API:

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

Le chiamate consumano crediti dell’account proprietario del token, misurati per token di
utilizzo. Sono separate dai job di trascrizione (vedi la [guida per gli agenti](/locales/it/agents.md)).

## Requisiti

- Il token ha l’ambito `ai:use`. La preimpostazione Automazione dell’app non lo include,
  quindi selezionalo quando crei il token.
- Il token è stato creato da una sessione autenticata dell’app KolWrite. I token più vecchi,
  non legati a un prodotto, vengono rifiutati con `legal_product_required`: creane uno nuovo.
- L’account ha accettato nell’app l’informativa in vigore sull’IA di terze parti. Fino ad allora
  l’API risponde HTTP 428 con `legal_acceptance_required`.
- L’accesso all’API è attivato per l’account (Impostazioni → Account → Accesso API).

## Endpoint

| Endpoint | Cosa fa |
|---|---|
| `GET /models` | I modelli che puoi usare, con `credit_pricing` per ciascuno |
| `POST /chat/completions` | Risposte di chat, con streaming (`"stream": true`) |
| `POST /responses` | L’API Responses |
| `POST /embeddings` | Embeddings |
| `POST /audio/transcriptions` | Testo di una breve clip vocale (`file` in multipart) |
| `POST /images/generations` | Generazione di immagini |

I modelli hanno alias stabili: `kw-auto` (sceglie tra un modello veloce e uno più
potente), `kw-fast` e `kw-pro`. `GET /models` è la fonte di riferimento per ciò che è
disponibile con il tuo token; ogni voce riporta `context_window` e il supporto a strumenti,
visione e 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
```

## Clip breve o registrazione completa?

`/audio/transcriptions` è una via rapida per le clip brevi: una richiesta, una risposta,
nessun job. Non produce etichette dei parlanti né la trascrizione salvata con le versioni.
Per una riunione, un’intervista o un file lungo, carica il file multimediale e crea un job di
trascrizione: restituisce tempi per parola, parlanti, SRT e VTT.

Con `want_words=true` la risposta per la clip contiene anche `words` come `{w, start, end}` in
secondi dall’inizio della clip.

## Cosa cambia rispetto a OpenAI

- I nomi dei modelli sono alias di KolWrite, non nomi di modelli OpenAI.
- Il token è un token di accesso personale di KolWrite, fatturato in crediti KolWrite.
- `kw-max` non è disponibile con i token API.
- Gli errori usano `detail.code`, come in [errori](/locales/it/errors.md).

## Domande

### Posso usare l’SDK di OpenAI con KolWrite?

Sì. Imposta l’URL di base su `https://api.kolwrite.com/api/v1/ai/openai` e la chiave API su
un token KolWrite con l’ambito `ai:use`.

### Sono supportati lo streaming e gli strumenti?

Le risposte di chat usano lo streaming con `"stream": true`. `GET /models` indica, per ogni
modello, se supporta strumenti, visione e audio.

### Quale endpoint trascrive l’audio?

`POST /audio/transcriptions` per le clip brevi; i job di trascrizione per tutto il resto.