KolWrite KolWrite المطورون

واجهة KolWrite البرمجية لوكلاء الذكاء الاصطناعي

كيف تتيح لوكيل ذكاء اصطناعي (Claude Code أو Codex أو Cursor أو سكربت من إعدادك) أن يحوّل التسجيلات إلى نصوص مفرّغة وترجمات SRT وتوقيتات للكلمات عبر واجهة منصة KolWrite على العنوان https://api-prod.kolwrite.com. يُنشئ شخص ما رمزًا مرة واحدة، ثم يقرؤه الوكيل من متغير بيئة ويستدعي HTTPS مباشرة. لا حاجة إلى حزمة SDK.

هذه واجهة المنصة التي تعمل برموز kol_. أما واجهة الرصيد على https://app.kolwrite.com (الترويسة x-api-key) فهي واجهة مختلفة، وتجد وصفها (بالإنجليزية) في https://console.kolwrite.com/llms.txt للاطلاع.

إذا كنت تفضّل التثبيت الجاهز على كتابة الاستدعاءات بنفسك، فإن وحدة تحكم واجهة API توفّر حزم تثبيت جاهزة لواجهة الرصيد: خادم MCP لكلٍ من Claude Code وCodex وCursor وGemini CLI، وskill للوكيل، بالإضافة إلى kolwrite.py وهو عميل Python في ملف واحد. تستخدم هذه الأدوات مفتاح API من console.kolwrite.com وليس رمز kol_. ابدأ من https://console.kolwrite.com/agents/؛ والملفان متاحان عبر https://console.kolwrite.com/cli/kolwrite.py وhttps://console.kolwrite.com/skills/kolwrite-transcribe.zip.

1. امنح الوكيل رمزًا

المهمةالنطاقات
التفريغ والتصديرfiles:write وjobs:write وjobs:read وtranscripts:read
ومعها فحص الرصيدأضف billing:read
نقاط النهاية المتوافقة مع OpenAIai:use (يستهلك الرصيد؛ وليس ضمن الإعداد الجاهز Automation في التطبيق)
إنشاء روابط المشاركةأضف shares:write

الصق هذا في AGENTS.md أو CLAUDE.md أو .cursorrules:

## KolWrite platform API
- Base URL https://api-prod.kolwrite.com. The token is in the environment variable KOLWRITE_TOKEN: send it as "Authorization: Bearer $KOLWRITE_TOKEN" and never print it.
- Flow: POST /api/v1/media/upload-session, PUT the bytes to data.upload_url, POST /api/v1/media/complete, POST /api/v1/jobs, poll GET /api/v1/jobs/{job_id} until status is succeeded, then GET /api/v1/jobs/{job_id}/export?format=json
- Spec: https://kolwrite-docs.pages.dev/openapi.json. Guide: https://kolwrite-docs.pages.dev/agents.md

2. أي استدعاء تستخدم

ما تريدهالاستدعاء
نص مفرّغ لملف، مع توقيتات الكلمات والمتحدثينجلسة رفع، ثم POST /api/v1/jobs (type: transcription)، ثم GET /api/v1/jobs/{job_id}/export?format=json
ترجمات SRT أو VTTGET /api/v1/jobs/{job_id}/export?format=srt أو format=vtt
ترجمات بلغة أخرىoptions.target_language في المهمة، ثم التصدير
نص عاديexport?format=text
Word أو PDFexport?format=docx أو format=pdf
النص بعد أن صحّحه الأشخاص في التطبيقGET /api/v1/workspace-files/{workspace_file_id}/transcript?format=json (تصدير المهمة يتضمن التصحيحات نفسها)
النصوص التي وضع شخص عليها علامة كمُراجَعة فقطGET /api/v1/workspace-files/{workspace_file_id}/transcript?require_reviewed=true, أو استطلع GET /api/v1/transcript-reviews?since=...
استدعاء عند انتهاء مهمة أو مراجعة نصPOST /api/v1/webhook-endpoints (النطاق webhooks:manage)؛ تحقق من KolWrite-Signature
نص لمقطع صوتي قصير، بلا مهمةPOST /api/v1/ai/openai/audio/transcriptions
محادثة واستجابات وتضمينات/api/v1/ai/openai/* (نقاط النهاية المتوافقة مع OpenAI)
النص المحفوظ بإصداراتهGET /api/v1/jobs/{job_id}/artifacts
رصيد الحسابGET /api/v1/billing/balance
رابط عام لنص مفرّغPOST /api/v1/shares
ملفات النماذج المتاحةGET /api/v1/models

3. تفريغ ملف بلغة Python

import json, mimetypes, os, time
import requests

BASE = "https://api-prod.kolwrite.com"
TOKEN = os.environ["KOLWRITE_TOKEN"]


def call(method, path, **kw):
    headers = {"Authorization": f"Bearer {TOKEN}", **kw.pop("headers", {})}
    r = requests.request(method, BASE + path, headers=headers, timeout=120, **kw)
    r.raise_for_status()
    return r


def transcribe(path, profile="oracle", language="auto"):
    name, size = os.path.basename(path), os.path.getsize(path)
    ctype = mimetypes.guess_type(name)[0] or "application/octet-stream"
    session = call("POST", "/api/v1/media/upload-session",
                   json={"filename": name, "file_size_bytes": size,
                         "content_type": ctype}).json()["data"]
    with open(path, "rb") as f:
        requests.put(session["upload_url"], data=f, headers=session["headers"],
                     timeout=3600).raise_for_status()
    media = call("POST", "/api/v1/media/complete",
                 json={"finalize_token": session["finalize_token"]}).json()["data"]
    job = call("POST", "/api/v1/jobs",
               headers={"Idempotency-Key": f"{name}-{size}-{profile}-{language}"},
               json={"type": "transcription",
                     "input": {"type": "media_ref", "media_id": media["media_id"]},
                     "profile": profile,
                     "options": {"language": language,
                                 "diarization": {"mode": "regular"}}}).json()["data"]
    while True:
        status = call("GET", f"/api/v1/jobs/{job['job_id']}").json()["data"]["status"]
        if status in ("succeeded", "failed", "cancelled"):
            break
        time.sleep(5)
    if status != "succeeded":
        raise RuntimeError(f"job {job['job_id']} {status}")
    export = call("GET", f"/api/v1/jobs/{job['job_id']}/export",
                  params={"format": "json"}).json()
    return job["job_id"], json.loads(export["data"])  # data is a JSON string


job_id, transcript = transcribe("interview.wav")
for seg in transcript["segments"]:
    print(f"{seg['start']:.2f}-{seg['end']:.2f} {seg.get('speaker', '')} {seg['text']}")

تُرفع الملفات الكبيرة على أجزاء: تُعيد الجلسة حينها data.upload_url بقيمة null وعنوان URL لكل جزء في data.multipart_part_urls (راجع البدء السريع).

4. استخدم التوقيتات

يتضمن تصدير JSON الحقل segments، ولكل مقطع start وend بالثواني، وtext، وspeaker عند تشغيل فصل المتحدثين، وwords (text وstart وend). دع الوكيل يختار المقاطع بحسب رقمها ويقرأ الأزمنة من النص المفرّغ؛ ولا تدع النموذج يكتب الطوابع الزمنية بنفسه.

import subprocess

keep = [s for s in transcript["segments"] if "pricing" in s["text"].lower()]
for i, seg in enumerate(keep):
    subprocess.run(["ffmpeg", "-y", "-i", "talk.mp4", "-ss", str(seg["start"]),
                    "-to", str(seg["end"]), f"clip{i}.mp4"], check=True)

تأتي الترجمات مباشرة من الواجهة. يحذف include_speakers=false أسماء المتحدثين، ويحدد max_chars_per_entry طول كل سطر ترجمة:

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" -o talk.srt \
  "https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=false&max_chars_per_entry=42"

تنزيل SRT وVTT مجاني في كل الخطط.

5. قواعد للوكلاء

أسئلة

كيف أصنع ترجمات SRT من فيديو باستخدام وكيل ذكاء اصطناعي؟

ارفع الملف، وأنشئ مهمة تفريغ، وانتظر حتى تصبح الحالة succeeded، ثم استدعِ نقطة التصدير مع format=srt.

هل يستطيع Claude Code أو Codex استدعاء واجهة KolWrite؟

نعم. يستدعيانها عبر HTTPS برمز وصول شخصي من متغير بيئة. لا توجد حزمة SDK ولا خادم MCP لتثبيته.

كيف يحصل الوكيل على الطوابع الزمنية لكل كلمة؟

صدّر المهمة بصيغة JSON. يحمل كل مقطع words مع start وend بالثواني.

نسخة Markdown من هذه الصفحة