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

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

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

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

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.

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.

Versione Markdown di questa pagina