# נקודות קצה תואמות OpenAI

ה-AI המנוהל של KolWrite עונה בצורות של ה-API של OpenAI. כוונו SDK של OpenAI,
או כל כלי שמאפשר להגדיר כתובת בסיס, אל KolWrite, והשתמשו באסימון גישה אישי
כמפתח ה-API:

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

הקריאות צורכות קרדיטים מהחשבון שמחזיק באסימון, לפי שימוש בטוקנים. הן נפרדות
ממשימות תמלול (ראו את [מדריך הסוכנים](/locales/he/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` | הטמעות (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/he/errors.md).

## שאלות

### אפשר להשתמש ב-SDK של OpenAI עם KolWrite?

כן. הגדירו את כתובת הבסיס ל-`https://api.kolwrite.com/api/v1/ai/openai` ואת מפתח
ה-API לאסימון KolWrite עם ההיקף `ai:use`.

### האם יש תמיכה בסטרימינג ובכלים?

השלמות צ'אט נתמכות בסטרימינג עם `"stream": true`. `GET /models` מראה לכל מודל אם
הוא תומך בכלים, בראייה ובשמע.

### איזו נקודת קצה מתמללת אודיו?

`POST /audio/transcriptions` להקלטות קצרות; משימות תמלול לכל השאר.