# كيف تنشئ ترجمات SRT من فيديو عبر واجهة برمجية > أرسل الفيديو إلى POST /transcribe مع ضبط output_format على srt وword_timestamps على false، وانتظر انتهاء المهمة، ثم احفظ النص الناتج في ملف بامتداد .srt. وإذا أردت ترجمة النص إلى لغة أخرى، أضف المعامل translate_to. يشرح هذا الدليل تفاصيل الطلب، وبنية ملف SRT، وطريقة تكوين أسطر متناسقة بالاعتماد على توقيت الكلمات، والتحويل إلى WebVTT، وحرق الترجمة على الفيديو. آخر تحديث: 2026-10-18 · HTML: https://console.kolwrite.com/ar/guides/srt-subtitles-api ## الطلب استدعاءان: ابدأ المهمة ثم استعلم عنها. و`result` في مهمة `srt` المكتملة سلسلة نصية لا JSON. هذه النسخة تحتاج curl وjq فقط: ```bash # 1. Start the job. "word_timestamps": false gives one cue per segment. JOB=$(curl -s https://app.kolwrite.com/transcribe \ -H "x-api-key: $KOLWRITE_API_KEY" -H "Content-Type: application/json" \ -d '{"audio_url": "https://example.com/talk.mp3", "model": "oracle", "output_format": "srt", "word_timestamps": false}' \ | jq -r .jobId) # 2. Poll until it is done and save the result string as a .srt file. while true; do REPLY=$(curl -s "https://app.kolwrite.com/transcribe/$JOB" -H "x-api-key: $KOLWRITE_API_KEY") STATUS=$(echo "$REPLY" | jq -r .status) if [ "$STATUS" = "COMPLETED" ]; then echo "$REPLY" | jq -r .result > talk.srt; break; fi if [ "$STATUS" = "FAILED" ]; then echo "$REPLY" | jq -r .error; break; fi sleep 5 done ``` يصلح إرسال ملف فيديو أيضًا لأن الواجهة تقرأ مسار الصوت منه. ويمر الملف المحلي أولًا عبر `POST /upload` (حتى 100 MiB)، أما للفيديو الطويل فاستخرج الصوت باستخدام ffmpeg. وتنجز الدالة المساعدة في [دليل تحرير الفيديو](https://console.kolwrite.com/ar/guides/video-editing-with-ai) الأمرين بلغة Python. ## ما بداخل ملف SRT عند ضبط `"word_timestamps": false`، يظهر لك سطر واحد لكل مقطع، وهذا هو الشكل المعتاد لملفات الترجمة: ```text 1 00:00:01,000 --> 00:00:03,750 Hello everyone and welcome to the show. 2 00:00:05,000 --> 00:00:07,750 Today we talk about editing video from a transcript. ``` أما إذا تركت توقيت الكلمات مفعلًا (وهو الإعداد الافتراضي)، فستعيد الواجهة سطرًا مستقلًا لكل كلمة. يكرر كل سطر نص المقطع كاملًا ويضع الكلمة المنطوقة حينها داخل وسم `` باللون الأصفر، ليظهر النص بأسلوب تظليل الكلمات مع الصوت بدل الترجمة العادية: ```text 1 00:00:01,000 --> 00:00:01,350 Hello everyone and welcome to the show. 2 00:00:01,400 --> 00:00:01,750 Hello everyone and welcome to the show. ``` إذا أردت ترجمة عادية، مرّر `"word_timestamps": false`، أو جمّع الأسطر بنفسك من كلمات ملف JSON بالطريقة التالية. ## تجميع أسطر مرتبة من توقيت الكلمات اطلب الصيغة `output_format: "json"` وجمّع الكلمات في أسطر بنفسك، بحيث لا يتجاوز السطر 42 حرفًا و6 ثوانٍ، وابدأ سطرًا جديدًا بعد كل وقفة. يمنحك هذا تحكمًا في طول السطر، وهو أمر مهم عند دمج الترجمة في الفيديو. srt_tools.py ```python # srt_tools.py — neat subtitle cues from word timings def srt_time(seconds): ms = round(seconds * 1000) h, ms = divmod(ms, 3_600_000) m, ms = divmod(ms, 60_000) s, ms = divmod(ms, 1000) return f"{h:02}:{m:02}:{s:02},{ms:03}" def cues_from_words(words, max_chars=42, max_seconds=6.0, max_gap=0.8): """Group timed words into subtitle cues: (start, end, text).""" cues, line = [], [] for word in words: text = word["word"].strip() if not text: continue if line: length = sum(len(w["word"]) + 1 for w in line) + len(text) if (length > max_chars or word["end"] - line[0]["start"] > max_seconds or word["start"] - line[-1]["end"] > max_gap): cues.append(line) line = [] line.append({"start": word["start"], "end": word["end"], "word": text}) if line: cues.append(line) return [(c[0]["start"], c[-1]["end"], " ".join(w["word"] for w in c)) for c in cues] def cues_from_result(result): """Cues for a whole JSON result; a segment without word times becomes one cue.""" cues = [] for segment in result["segments"]: if segment.get("words"): cues += cues_from_words(segment["words"]) elif segment["text"].strip(): cues.append((segment["start"], segment["end"], segment["text"].strip())) return cues def write_srt(cues, path): with open(path, "w", encoding="utf-8") as out: for number, (start, end, text) in enumerate(cues, 1): out.write(f"{number}\n{srt_time(start)} --> {srt_time(end)}\n{text}\n\n") ``` تُخرج الدالة `cues_from_result(result)` قوائم ثلاثية على شكل `(start, end, text)` للنتيجة كاملة، وتعتمد تلقائيًا على توقيت المقطع إذا لم يُرجع النموذج توقيت الكلمات. بعد ذلك، تتولى `write_srt(cues, "talk.srt")` كتابة الملف. ## ترجمة النص إلى لغة أخرى مرّر المعامل `translate_to` مع رمز اللغة المطلوبة واستخدم أحد نماذج Oracle (نموذج `oracle_mini` هو الأقل تكلفة بين النماذج التي تدعم الترجمة). ستحصل على الأسطر مترجمة إلى اللغة الهدف. احرص على إبقاء `word_timestamps` على القيمة false ليمثل كل سطر مقطعًا كاملًا. ```json { "audio_url": "https://example.com/lecture-he.mp4", "model": "oracle_mini", "language": "he", "translate_to": "en", "output_format": "srt", "word_timestamps": false } ``` إذا أردت ترجمة الفيديو نفسه إلى عدة لغات، أرسل مهمة مستقلة لكل لغة. تعامل مع الترجمة الآلية كمسودة أولى، وراجع الأسماء والأرقام والمصطلحات قبل نشرها. ## التحويل إلى WebVTT وASS وصيغ أخرى تُخرج الواجهة صيغ `json` أو `txt` أو `srt` فقط. إذا كنت تحتاج إلى ملف WebVTT لتشغيله داخل وسم `