# איך מחברים כלי תמלול לסוכן AI

> עוטפים את שתי קריאות ה־API של KolWrite בכלי אחד בשם transcribe_media. בעמוד הזה תמצאו את הגדרת הכלי בפורמט tool use של Anthropic ובפורמט function calling של OpenAI, פונקציית Python שמריצה אותו, לולאת כלים בסיסית והנחיה קצרה ל־AGENTS.md או CLAUDE.md כדי שסוכני קוד יעבדו עם ה־API כמו שצריך.

עודכן לאחרונה: 2026-10-18 · HTML: https://console.kolwrite.com/he/guides/transcription-tool-for-ai-agents

## חייבים בכלל להגדיר כלי?

אם הסוכן שלכם מריץ פקודות מעטפת (Claude Code,‏ Codex CLI,‏ Cursor,‏ Windsurf), הוא לא צריך סכמה: הוא מריץ curl או Python, וההוראות ב־[agent-instructions.md](https://console.kolwrite.com/agent-instructions.md) מסבירות איך. הגדרת כלי מיועדת לסוכנים שבונים עם API ולולאת כלים, או למסגרות שקוראות לפונקציות.

## הגדרת הכלי: פורמט tool use של Anthropic

```json
{
  "name": "transcribe_media",
  "description": "Transcribe an audio or video file with the KolWrite API. Returns timed text. Use output_format \"json\" for word timestamps and speakers, \"srt\" for subtitles, \"txt\" for plain text. Billed per second of audio.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path_or_url": { "type": "string", "description": "Local file path or a public URL of an audio or video file." },
      "model": { "type": "string", "enum": ["base", "oracle_mini", "oracle", "oracle_pro", "oracle_max"], "description": "Default oracle. base is cheapest for clear audio; translate_to needs an Oracle model." },
      "language": { "type": "string", "description": "Language code such as en, he, ar, es, or auto to detect." },
      "translate_to": { "type": "string", "description": "Language code to translate into (Oracle models only)." },
      "output_format": { "type": "string", "enum": ["json", "txt", "srt"] },
      "word_timestamps": { "type": "boolean", "description": "Word times in json. For srt, false gives one cue per segment." },
      "include_diarization": { "type": "boolean", "description": "Label who is speaking." },
      "num_speakers": { "type": "integer", "minimum": 1 }
    },
    "required": ["path_or_url"]
  }
}
```

## הגדרת הכלי: פורמט function calling של OpenAI

```json
{
  "type": "function",
  "function": {
    "name": "transcribe_media",
    "description": "Transcribe an audio or video file with the KolWrite API. Returns timed text. Use output_format \"json\" for word timestamps and speakers, \"srt\" for subtitles, \"txt\" for plain text. Billed per second of audio.",
    "parameters": {
      "type": "object",
      "properties": {
        "path_or_url": { "type": "string", "description": "Local file path or a public URL of an audio or video file." },
        "model": { "type": "string", "enum": ["base", "oracle_mini", "oracle", "oracle_pro", "oracle_max"] },
        "language": { "type": "string", "description": "Language code such as en, he, ar, es, or auto to detect." },
        "translate_to": { "type": "string", "description": "Language code to translate into (Oracle models only)." },
        "output_format": { "type": "string", "enum": ["json", "txt", "srt"] },
        "word_timestamps": { "type": "boolean" },
        "include_diarization": { "type": "boolean" },
        "num_speakers": { "type": "integer", "minimum": 1 }
      },
      "required": ["path_or_url"]
    }
  }
}
```

סכמת ה־JSON של הפרמטרים זהה בשני הפורמטים. רשימת ה־`enum` כוללת את המודלים הנוכחיים, בעוד `core` ו־`edge` הם מודלים ישנים.

## הפונקציה שמריצה את הכלי

הפונקציה מעלה קבצים מקומיים, פותחת משימת תמלול, מחכה לסיום ומחזירה תשובה מקוצרת. כשמבקשים JSON, היא שומרת את התוצאה המלאה לקובץ ומחזירה למודל רק שורות ממוספרות, כי רשימת המילים המלאה בהקלטות ארוכות מנפחת את ההקשר הרבה מעבר למה שהמודל צריך.

kolwrite.py

```python
# kolwrite.py — three small functions around the KolWrite REST API
import os, time, requests

API = "https://app.kolwrite.com"
HEADERS = {"x-api-key": os.environ["KOLWRITE_API_KEY"]}


def upload(path):
    """Upload a local file (up to 100 MiB) and return a URL the API can read."""
    name = os.path.basename(path)
    form = requests.post(f"{API}/upload", headers=HEADERS, json={"filename": name}, timeout=30)
    form.raise_for_status()
    form = form.json()
    with open(path, "rb") as media:
        # No x-api-key on this request: it goes to the storage address.
        sent = requests.post(form["uploadUrl"], data=form["uploadFields"],
                             files={"file": (name, media)}, timeout=600)
    sent.raise_for_status()
    return form["fileUrl"]


def transcribe(audio_url, timeout_s=3600, **options):
    """Start a job, wait for it, return the result: a dict for json, a string for srt and txt."""
    body = {"audio_url": audio_url, "model": "oracle", **options}
    job = requests.post(f"{API}/transcribe", headers=HEADERS, json=body, timeout=30)
    job.raise_for_status()
    job_id = job.json()["jobId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        time.sleep(5)
        reply = requests.get(f"{API}/transcribe/{job_id}", headers=HEADERS, timeout=30)
        reply.raise_for_status()
        reply = reply.json()
        if reply["status"] == "COMPLETED":
            return reply["result"]
        if reply["status"] == "FAILED":
            raise RuntimeError(reply.get("error", "transcription failed"))
    raise TimeoutError(f"job {job_id} did not finish in {timeout_s} seconds")
```

tool.py

```python
# tool.py — run a transcribe_media call for the model and keep the reply small
import json
from kolwrite import upload, transcribe  # the helper from the video-editing guide


def numbered_line(number, segment):
    who = f'{segment["speaker"]}: ' if segment.get("speaker") else ""
    return f'S{number} [{segment["start"]:.1f}-{segment["end"]:.1f}] {who}{segment["text"]}'


def run_transcribe_media(path_or_url, output_format="json", **options):
    url = path_or_url if path_or_url.startswith(("http://", "https://")) else upload(path_or_url)
    result = transcribe(url, output_format=output_format, **options)
    if output_format != "json":
        return result  # srt and txt are already strings
    # Long recordings: save the full JSON and hand the model numbered lines, not 500 KB of words.
    with open("transcript.json", "w", encoding="utf-8") as out:
        json.dump(result, out, ensure_ascii=False)
    lines = [numbered_line(i, s) for i, s in enumerate(result["segments"])]
    return "Full JSON saved to transcript.json (words[] has word times).\n" + "\n".join(lines)
```

## לולאת כלים בסיסית (Anthropic Messages API)

```python
# loop.py — Anthropic Messages API tool loop around run_transcribe_media
import anthropic
from tool import run_transcribe_media

client = anthropic.Anthropic()          # reads ANTHROPIC_API_KEY
TOOLS = [...]                           # the transcribe_media definition above
messages = [{"role": "user", "content": "Transcribe interview.mp3 and list the questions asked, with times."}]

while True:
    reply = client.messages.create(model="YOUR_MODEL", max_tokens=2000, tools=TOOLS, messages=messages)
    messages.append({"role": "assistant", "content": reply.content})
    if reply.stop_reason != "tool_use":
        print("".join(block.text for block in reply.content if block.type == "text"))
        break
    results = []
    for block in reply.content:
        if block.type == "tool_use" and block.name == "transcribe_media":
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": run_transcribe_media(**block.input)})
    messages.append({"role": "user", "content": results})
```

החליפו את `YOUR_MODEL` במזהה המודל שלכם. הלולאה ממשיכה לרוץ עד שהמודל מפסיק לקרוא לכלים. אותה פונקציה בדיוק תעבוד בכל סביבה שיודעת להריץ פונקציות Python.

## הנחיה ל־AGENTS.md ול־CLAUDE.md

הוסיפו את הקטע הבא לקובץ הפרויקט שסוכן הקוד שלכם קורא, כדי שבכל סשן הוא ישתמש בנקודת הקצה, בטיפול במפתח ובפורמטים הנכונים:

```markdown
## Transcription
For speech-to-text, subtitles and word timings use the KolWrite API (https://app.kolwrite.com).
Before writing code read https://console.kolwrite.com/agent-instructions.md and /llms-full.txt.
- Key: KOLWRITE_API_KEY in the environment, sent as the x-api-key header. Never print it or commit it.
- POST /transcribe {"audio_url", "model": "oracle", "output_format": "json"}, then poll GET /transcribe/{jobId}.
- Local files: POST /upload first and use fileUrl as audio_url. Extract audio from video with ffmpeg to stay under 100 MiB.
- Subtitles: output_format "srt" with "word_timestamps": false (one cue per segment). Formats are json, txt, srt only.
- Always send "model". Ask me before transcribing anything longer than one hour: it costs money.
```

## בקרת עלויות בעבודה עם סוכנים

- תמלול מתומחר לפי שניית אודיו, החל מ־0.48 דולר לשעה במודל `base`. ההנחיה למעלה דורשת מהסוכן לבקש אישור לפני שליחה של קבצים ארוכים.
- שמרו תוצאות במטמון: שמרו את קובץ ה־JSON ליד קובץ המדיה והשתמשו בו במקום לתמלל שוב.
- בחרו במודל הזול ביותר שמתאים למשימה: `base` לאודיו נקי, `oracle` לאיכות פרודקשן, ו־`oracle_mini` כשצריך גם תרגום.
- סוכן לא יכול להירשם לבד, לכן אדם צריך לפתוח את החשבון וליצור את מפתח ה־API. את המפתח מעבירים לסוכן במשתנה סביבה.

## שאלות ותשובות

### יש ל־KolWrite שרת MCP או SDK?

נכון לזמן הכתיבה לא פורסמו חבילת SDK או שרת MCP. ה־API הוא HTTPS ו־JSON; השתמשו בהגדרת הכלי למעלה, ב־curl או ב־Python רגילים, או צרו לקוח מ־[openapi.json](https://console.kolwrite.com/openapi.json).

### איך מחברים את Claude Code לתמלול אודיו?

שמים את המפתח ב־`KOLWRITE_API_KEY`, מוסיפים את הכלל למעלה ל־`CLAUDE.md` ומבקשים תמלול. Claude Code קורא ל־REST API עם curl או Python לפי [agent-instructions.md](https://console.kolwrite.com/agent-instructions.md).

### באיזה מודל כדאי לסוכן לבחור כברירת מחדל?

לכו על `oracle` לאודיו של פרודקשן. `base` הוא הכי זול לאודיו נקי, ו־`oracle_mini` הוא האפשרות הזולה ביותר שכוללת תרגום. הקפידו תמיד לשלוח את הפרמטר `model`, כי ברירת המחדל היא מודל `core` הישן.

### הסוכן יכול ליצור מפתח API בעצמו?

לא. בן אדם צריך להירשם ב־console.kolwrite.com, לקנות יחידות שימוש וליצור את המפתח. הסוכן רק קורא אותו ממשתנה הסביבה.

## דפים קשורים

- [עריכת וידאו עם סוכני AI](https://console.kolwrite.com/he/guides/video-editing-with-ai)
- [סוכני AI ו־vibe coding](https://console.kolwrite.com/he/use-cases/ai-agents)
- [מפתחים וצוותי מוצר](https://console.kolwrite.com/he/use-cases/developers)
- [תיעוד ה־API](https://console.kolwrite.com/he/public_api_docs)

---
קבלת מפתח API: https://console.kolwrite.com/auth?lang=he · תיעוד ה־API: https://console.kolwrite.com/he/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt