Endpoints compatíveis com OpenAI

Q: 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.

Q: 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.

Q: Qual endpoint transcreve áudio?

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

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).

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

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

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

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.

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.

Versão em Markdown desta página