# איך מקבלים חותמת זמן לכל מילה בהקלטה

> שולחים בקשה ל־POST /transcribe עם output_format מוגדר ל־json ו־word_timestamps מוגדר ל־true (שניהם ברירת מחדל). כל מקטע בתשובה יכלול מערך words עם אובייקטים של {start, end, word} בשניות. במדריך הזה נראה איך בנויה התשובה, אילו מודלים מחזירים זמני מילים ומה אפשר לבנות איתם.

עודכן לאחרונה: 2026-10-18 · HTML: https://console.kolwrite.com/he/guides/word-timestamps-api

## הבקשה

```json
{
  "audio_url": "https://example.com/interview.mp3",
  "model": "oracle",
  "language": "auto",
  "word_timestamps": true,
  "output_format": "json"
}
```

יוצרים משימה עם `POST /transcribe` ודוגמים את `GET /transcribe/{jobId}` עד שהסטטוס הוא `COMPLETED`. הקפידו לשלוח את הפרמטר `model` במפורש, כי בלעדיו ה־API משתמש במודל הישן `core`.

## התשובה

```json
{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 1.0,
        "end": 3.75,
        "text": "Hello everyone and welcome to the show.",
        "speaker": "Speaker 1",
        "words": [
          { "start": 1.0, "end": 1.35, "word": "Hello" },
          { "start": 1.4, "end": 1.75, "word": "everyone" }
        ]
      }
    ]
  }
}
```

- `segments[]`: כולל `start` ו־`end` בשניות, `text`, שדה `speaker` כשזיהוי דוברים פועל, ו־`words[]`.
- `words[]`: כולל `start`,‏ `end` ו־`word` בשניות, מעוגלים לשלוש ספרות אחרי הנקודה.
- למילה יכולים להיות ערכי `start` ו־`end` זהים, ומילה קצרה יכולה להימשך מאיות שנייה בודדות. אל תחלקו במשך הזמן של מילה.
- אם הגדרתם `word_timestamps` ל־`false`, או שהמודל החזיר רק זמני מקטעים, השדה `words` לא יופיע ויישארו לכם רק `start` ו־`end` ברמת המקטע.

## אילו מודלים מחזירים זמני מילים

| מודל | זמני מילים |
| --- | --- |
| `base`,‏ `oracle`,‏ `oracle_pro`,‏ `oracle_max` | כן |
| `oracle_mini` | זמני מקטעים בתמלול רגיל, וזמני מילים כשמצב דוברים (זיהוי דוברים או הפרדת ערוצים) פועל |
| `core`,‏ `edge` (ישנים) | כן |

בפלט טקסט (`txt`) אין זמנים. קובץ ה־SRT שה־API מייצר מושפע מאותו פרמטר, פרטים ב[מדריך ה־SRT](https://console.kolwrite.com/he/guides/srt-subtitles-api).

## איתור הזמן המדויק של ביטוי

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

find.py

```python
# find.py — where is a phrase said? Returns (start, end) in seconds.
import re


def find_phrase(result, phrase):
    words = [w for segment in result["segments"] for w in segment.get("words", [])]
    clean = lambda text: re.sub(r"[^\w]", "", text.lower())
    target = [clean(p) for p in phrase.split()]
    tokens = [clean(w["word"]) for w in words]
    for i in range(len(tokens) - len(target) + 1):
        if tokens[i:i + len(target)] == target:
            return words[i]["start"], words[i + len(target) - 1]["end"]
    return None


# start, end = find_phrase(result, "welcome to the show")
# ffmpeg -ss <start> -to <end> -i talk.mp4 -c:v libx264 -c:a aac clip.mp4
```

חיתוך קליפ לפי טווח זמן:

```bash
ffmpeg -ss 41.2 -to 47.8 -i talk.mp4 -c:v libx264 -c:a aac clip.mp4
```

## קיצור שתיקות וחיתוכי קפיצה

לפי זמני המילים אפשר לחשב את המרווחים ביניהן. משאירים רצפים של דיבור וחותכים החוצה עצירות שארוכות מסף מסוים:

silences.py

```python
# silences.py — keep the speech, drop pauses longer than max_gap seconds
def speech_ranges(words, max_gap=0.7, pad=0.1):
    ranges = []
    for word in words:
        if ranges and word["start"] - ranges[-1][1] <= max_gap:
            ranges[-1][1] = word["end"]
        else:
            ranges.append([word["start"], word["end"]])
    return [[max(0.0, s - pad), e + pad] for s, e in ranges]

# Pass the ranges to cut() from cut.py to build the tightened video.
```

את הטווחים שנשארו מחברים בעזרת `cut()` מ[מדריך עריכת הווידאו](https://console.kolwrite.com/he/guides/video-editing-with-ai).

## שימושים נוספים בזמני מילים

- הדגשת מילים בזמן ניגון בווב: מדגישים את המילה שטווח הזמן שלה מכיל את `currentTime`.
- תמליל לחיץ: כל מילה מקשרת ל־`?t=<start>` בנגן.
- חלוקה לפרקים ורגעים מרכזיים: ה־LLM בוחר מספרי מקטעים, והקוד מתרגם אותם לזמנים.
- חיפוש בארכיון הקלטות: שומרים באינדקס את המילים יחד עם זמן ההתחלה שלהן, כדי שלחיצה על תוצאה תפתח את ההקלטה בשנייה הנכונה.
- יישור טקסט ועבודה על קורפוסים: ממירים את זמני המילים מה־JSON לפורמטי התיוג שהכלים שלכם עובדים איתם.

## כמה זה עולה

חותמות זמן למילים לא מוסיפות למחיר. החיוב הוא לפי שניית אודיו בהתאם למודל, החל מ־0.48 דולר לשעה ב־`base`. שעה במודל `oracle` עולה 1.44 דולר. מחירון מלא: [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

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

### איך מקבלים חותמות זמן ברמת המילה מ־API לתמלול?

שולחים בקשה עם `output_format: "json"` ו־`word_timestamps: true`. בכל מקטע בתשובה יחזור מערך `words[]` עם `start`,‏ `end` ו־`word` בשניות.

### אילו מודלים תומכים בחותמות זמן למילים?

המודלים `base`,‏ `oracle`,‏ `oracle_pro` ו־`oracle_max` מחזירים אותן. המודל `oracle_mini` מחזיר זמני מקטעים, אלא אם מפעילים מצב דוברים. בפלט טקסט אין חותמות זמן.

### עד כמה זמני המילים מדויקים?

KolWrite לא מפרסמת מדד דיוק לפי שפה עבור ה־API הזה. הזמנים מתאימים לחיתוך בין מילים ולהדגשת טקסט, אבל מומלץ לבדוק מדגם מההקלטות שלכם ולהשאיר מרווח ביטחון קטן בנקודות החיתוך.

### אפשר לקבל חותמות זמן לקובץ וידאו?

כן. ה־API קורא את ערוץ האודיו מתוך קובץ הווידאו. אם הקובץ שוקל מעל 100 MiB, חלצו ממנו קודם את האודיו עם ffmpeg.

### חותמות הזמן הן בשניות או באלפיות שנייה?

בשניות, כמספר עשרוני עם עד שלוש ספרות אחרי הנקודה (למשל `41.236`).

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

- [עריכת וידאו עם סוכני AI](https://console.kolwrite.com/he/guides/video-editing-with-ai)
- [API לכתוביות SRT](https://console.kolwrite.com/he/guides/srt-subtitles-api)
- [כתוביות לפודקאסטים וליוטיוב](https://console.kolwrite.com/he/guides/podcast-youtube-captions)
- [מחקר שפה ובלשנות](https://console.kolwrite.com/he/use-cases/researchers)
- [מפתחים וצוותי מוצר](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