# Endpoints compatíveis com OpenAI

A IA gerenciada do KolWrite responde nos mesmos formatos da API da OpenAI. Aponte um SDK da
OpenAI, ou qualquer ferramenta em que se possa definir uma URL base, para o KolWrite e use
um token de acesso pessoal como chave de API:

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

As chamadas gastam créditos da conta dona do token, medidos por tokens de uso. São separadas
das tarefas de transcrição (veja o [guia para agentes](/locales/pt/agents.md)).

## Requisitos

- O token tem o escopo `ai:use`. A predefinição Automação do app não o inclui,
  então marque-o ao criar o token.
- O token foi criado a partir de uma sessão iniciada no app KolWrite. Tokens antigos, sem
  vínculo com um produto, são recusados com `legal_product_required`: crie um novo.
- A conta aceitou no app a divulgação vigente sobre IA de terceiros. Até lá, a API
  responde HTTP 428 com `legal_acceptance_required`.
- O acesso à API está ativado para a conta (Configurações → Conta → Acesso à API).

## Endpoints

| Endpoint | O que faz |
|---|---|
| `GET /models` | Os modelos que você pode usar, com `credit_pricing` de cada um |
| `POST /chat/completions` | Respostas de chat, com streaming (`"stream": true`) |
| `POST /responses` | A API Responses |
| `POST /embeddings` | Embeddings |
| `POST /audio/transcriptions` | Texto de um clipe de voz curto (`file` em multipart) |
| `POST /images/generations` | Geração de imagens |

Os modelos têm apelidos estáveis: `kw-auto` (escolhe entre um modelo rápido e outro mais
forte), `kw-fast` e `kw-pro`. `GET /models` é a fonte oficial do que está disponível para o
seu token; cada entrada informa `context_window` e se há suporte a ferramentas, visão e áudio.

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

## Clipe curto ou gravação completa?

`/audio/transcriptions` é um caminho rápido para clipes curtos: uma requisição, uma resposta,
sem tarefa. Ele não gera rótulos de falantes nem a transcrição salva com versões. Para uma
reunião, uma entrevista ou um arquivo longo, envie a mídia e crie uma tarefa de transcrição:
ela devolve tempos por palavra, falantes, SRT e VTT.

Com `want_words=true`, a resposta do clipe traz também `words` como `{w, start, end}` em
segundos a partir do início do clipe.

## O que muda em relação à OpenAI

- Os nomes de modelo são apelidos do KolWrite, não nomes de modelos da OpenAI.
- O token é um token de acesso pessoal do KolWrite, cobrado em créditos do KolWrite.
- `kw-max` não está disponível com tokens de API.
- Os erros usam `detail.code`, como em [erros](/locales/pt/errors.md).

## Perguntas

### Posso usar o SDK da OpenAI com o KolWrite?

Pode. Defina a URL base como `https://api.kolwrite.com/api/v1/ai/openai` e a chave de API como
um token do KolWrite com o escopo `ai:use`.

### Há suporte a streaming e a ferramentas?

As respostas de chat usam streaming com `"stream": true`. `GET /models` informa, por modelo,
se há suporte a ferramentas, visão e áudio.

### Qual endpoint transcreve áudio?

`POST /audio/transcriptions` para clipes curtos; tarefas de transcrição para todo o resto.