# نقاط النهاية المتوافقة مع OpenAI

يردّ الذكاء الاصطناعي المُدار في KolWrite بنفس صيغ واجهة OpenAI. وجّه حزمة OpenAI SDK،
أو أي أداة تتيح تحديد عنوان أساسي، إلى KolWrite، واستخدم رمز وصول شخصي
بوصفه مفتاح API:

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

تستهلك الاستدعاءات رصيدًا من الحساب الذي يملك الرمز، بحسب الاستخدام بالرموز النصية (tokens). وهي منفصلة عن مهام التفريغ
(راجع [دليل الوكلاء](/locales/ar/agents.md)).

## المتطلبات

- للرمز النطاق `ai:use`. الإعداد الجاهز Automation في التطبيق لا يتضمنه،
  فحدّده عند إنشاء الرمز.
- أُنشئ الرمز من جلسة مسجّلة الدخول في تطبيق KolWrite. تُرفض الرموز الأقدم غير المرتبطة
  بمنتج برمز الخطأ `legal_product_required`: أنشئ رمزًا جديدًا.
- قبل الحساب في التطبيق إفصاح الجهات الخارجية للذكاء الاصطناعي بصيغته الحالية. وإلى
  ذلك الحين تردّ الواجهة بـ HTTP 428 مع `legal_acceptance_required`.
- الوصول إلى الواجهة مفعّل للحساب (الإعدادات ← الحساب ← الوصول إلى API).

## نقاط النهاية

| نقطة النهاية | وظيفتها |
|---|---|
| `GET /models` | النماذج التي يمكنك استخدامها، مع `credit_pricing` لكل منها |
| `POST /chat/completions` | إكمالات المحادثة، مع البث (`"stream": true`) |
| `POST /responses` | واجهة Responses |
| `POST /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/ar/errors.md).

## أسئلة

### هل يمكنني استخدام OpenAI SDK مع KolWrite؟

نعم. اضبط العنوان الأساسي على `https://api.kolwrite.com/api/v1/ai/openai` ومفتاح API
على رمز KolWrite يحمل النطاق `ai:use`.

### هل يدعم البث والأدوات؟

تدعم إكمالات المحادثة البث مع `"stream": true`. ويخبرك `GET /models` لكل نموذج
هل يدعم الأدوات والرؤية والصوت.

### أي نقطة نهاية تفرّغ الصوت؟

`POST /audio/transcriptions` للمقاطع القصيرة؛ ومهام التفريغ لكل ما عدا ذلك.