# Endpoints compatibles con OpenAI

La IA gestionada de KolWrite responde con los mismos formatos que la API de OpenAI. Apunta
un SDK de OpenAI, o cualquier herramienta que permita fijar una URL base, a KolWrite y usa
un token de acceso personal como clave de API:

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

Las llamadas gastan créditos de la cuenta propietaria del token, medidos por tokens de uso.
Son independientes de los trabajos de transcripción (consulta la
[guía para agentes](/locales/es/agents.md)).

## Requisitos

- El token tiene el ámbito `ai:use`. El ajuste Automation de la app no lo incluye,
  así que márcalo al crear el token.
- El token se creó desde una sesión iniciada en la app de KolWrite. Los tokens antiguos
  que no están vinculados a un producto se rechazan con `legal_product_required`: crea uno nuevo.
- La cuenta ha aceptado en la app la divulgación vigente sobre IA de terceros. Hasta
  entonces la API responde HTTP 428 con `legal_acceptance_required`.
- El acceso a la API está activado para la cuenta (Ajustes → Cuenta → Acceso a la API).

## Endpoints

| Endpoint | Qué hace |
|---|---|
| `GET /models` | Los modelos que puedes usar, con `credit_pricing` de cada uno |
| `POST /chat/completions` | Completados de chat, con streaming (`"stream": true`) |
| `POST /responses` | La API Responses |
| `POST /embeddings` | Embeddings |
| `POST /audio/transcriptions` | Texto de un clip de voz corto (`file` en multipart) |
| `POST /images/generations` | Generación de imágenes |

Los modelos se nombran con alias estables: `kw-auto` (elige entre un modelo rápido y otro más
potente), `kw-fast` y `kw-pro`. `GET /models` es la fuente de verdad de lo que está disponible
para tu token; cada entrada indica `context_window` y si admite herramientas, visión y 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 clip corto o una grabación completa?

`/audio/transcriptions` es una vía rápida para clips cortos: una petición, una respuesta, sin
trabajo. No genera etiquetas de hablante ni la transcripción guardada con versiones. Para una
reunión, una entrevista o un archivo largo, sube el archivo multimedia y crea un trabajo de
transcripción: devuelve tiempos por palabra, hablantes, SRT y VTT.

Con `want_words=true` la respuesta del clip incluye además `words` como `{w, start, end}` en
segundos desde el inicio del clip.

## Qué se diferencia de OpenAI

- Los nombres de modelo son alias de KolWrite, no nombres de modelos de OpenAI.
- El token es un token de acceso personal de KolWrite y se factura en créditos de KolWrite.
- `kw-max` no está disponible con tokens de API.
- Los errores usan `detail.code`, como en [errores](/locales/es/errors.md).

## Preguntas

### ¿Puedo usar el SDK de OpenAI con KolWrite?

Sí. Fija la URL base en `https://api.kolwrite.com/api/v1/ai/openai` y la clave de API en un
token de KolWrite con el ámbito `ai:use`.

### ¿Admite streaming y herramientas?

El chat completa en streaming con `"stream": true`. `GET /models` indica, por modelo, si admite
herramientas, visión y audio.

### ¿Qué endpoint transcribe audio?

`POST /audio/transcriptions` para clips cortos; los trabajos de transcripción para todo lo demás.