# Эндпоинты, совместимые с OpenAI

Управляемый ИИ KolWrite отвечает в тех же форматах, что и API OpenAI. Направьте SDK OpenAI
или любой инструмент, где можно задать базовый URL, на KolWrite и используйте
персональный токен доступа как ключ API:

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

Вызовы тратят кредиты аккаунта, которому принадлежит токен, по расходу токенов. Они не
связаны с задачами расшифровки (см. [руководство для агентов](/locales/ru/agents.md)).

## Требования

- У токена есть область доступа `ai:use`. В набор Automation в приложении она не входит,
  поэтому отметьте её при создании токена.
- Токен создан из сессии, в которую выполнен вход в приложении KolWrite. Старые токены,
  не привязанные к продукту, отклоняются с `legal_product_required`: создайте новый.
- Аккаунт принял в приложении действующее уведомление об ИИ сторонних поставщиков. Пока
  этого нет, API отвечает HTTP 428 с `legal_acceptance_required`.
- Доступ к API включён для аккаунта (Настройки → Аккаунт → Доступ к API).

## Эндпоинты

| Эндпоинт | Что делает |
|---|---|
| `GET /models` | Доступные модели с `credit_pricing` для каждой |
| `POST /chat/completions` | Чат-ответы, в том числе потоком (`"stream": true`) |
| `POST /responses` | Responses API |
| `POST /embeddings` | Эмбеддинги |
| `POST /audio/transcriptions` | Текст короткой голосовой записи (`file` в multipart) |
| `POST /images/generations` | Генерация изображений |

Модели называются стабильными псевдонимами: `kw-auto` (выбирает между быстрой и более
сильной моделью), `kw-fast` и `kw-pro`. Что доступно вашему токену, надёжнее всего
показывает `GET /models`; каждая запись содержит `context_window` и сведения о поддержке
инструментов, зрения и звука.

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

## Короткий клип или полная запись?

`/audio/transcriptions` — быстрый путь для коротких клипов: один запрос, один ответ, без
задачи. Он не создаёт метки говорящих и сохранённую расшифровку с версиями. Для совещания,
интервью или длинного файла загрузите медиа и создайте задачу расшифровки: она возвращает
тайминги слов, говорящих, SRT и VTT.

С `want_words=true` ответ для клипа содержит ещё и `words` в виде `{w, start, end}` в
секундах от начала клипа.

## Чем это отличается от OpenAI

- Названия моделей — псевдонимы KolWrite, а не названия моделей OpenAI.
- Токен — персональный токен доступа KolWrite, расчёт ведётся в кредитах KolWrite.
- `kw-max` недоступна с API-токенами.
- Ошибки используют `detail.code`, как в разделе [ошибки](/locales/ru/errors.md).

## Вопросы

### Можно ли использовать SDK OpenAI с KolWrite?

Да. Задайте базовый URL `https://api.kolwrite.com/api/v1/ai/openai`, а ключом API
сделайте токен KolWrite с областью доступа `ai:use`.

### Поддерживаются ли потоковая передача и инструменты?

Чат-ответы идут потоком при `"stream": true`. `GET /models` показывает для каждой модели,
поддерживает ли она инструменты, зрение и звук.

### Какой эндпоинт расшифровывает аудио?

`POST /audio/transcriptions` — для коротких клипов; задачи расшифровки — для всего остального.