บทแนะนำเพื่อเริ่มต้นใช้งาน Loma Sub API

บทแนะนำนี้แสดงวิธีสร้างซับไตเติลจากไฟล์เสียงหรือวิดีโอที่อยู่ในเครื่อง ตั้งแต่การอัปโหลดไฟล์ไปยังพื้นที่จัดเก็บ การสร้างงานถอดเสียง การติดตามสถานะ ไปจนถึงการดาวน์โหลดไฟล์ซับไตเติล

เริ่มจากเข้าสู่ระบบ editor เปิดหน้าบัญชี แล้วสร้าง Personal API key คัดลอก key ที่แสดงครั้งเดียวมาใส่ LOMA_API_SECRET_KEY ใช้โควตาร่วมกับ editor และงานจาก CLI/SDK จะอยู่ในประวัติงานของคุณ ไม่ใช้ shared secret ของ worker

ใช้คำสั่งเดียวด้วย Node.js

แพ็กเกจ npm lomasub รวมขั้นตอนอัปโหลด สร้างงาน รอผล และดาวน์โหลด SRT ให้ในคำสั่งเดียว ใช้ Node.js 20 ขึ้นไปและ API key เรียกใช้ได้โดยตรงด้วย npx:

export LOMA_API_SECRET_KEY="<your-api-key>"
npx lomasub transcribe ./video.mp4 --language th --output ./video.srt

ถ้ามี ffmpeg ใน PATH โปรแกรมจะดึง audio stream แรกออกด้วย -c:a copy โดยไม่แปลง codec, sample rate หรือคุณภาพเสียง แล้วอัปโหลดเฉพาะเสียง หากไม่มี ffmpeg หรือดึงเสียงไม่สำเร็จ จะอัปโหลดไฟล์ต้นฉบับแทน ใช้ --no-ffmpeg เพื่อข้ามขั้นตอนนี้

ตั้งค่าขั้นสูงด้วย flags หรือ --config options.json ซึ่งอ่าน JSON object ของ config โดยตรง ค่า flags ที่ระบุจะทับค่าในไฟล์ ส่วนค่าที่ไม่ได้ระบุใช้ค่าเริ่มต้นจากเซิร์ฟเวอร์:

npx lomasub transcribe ./video.mp4 --speaker-diarization --srt-max-chars 48 --srt-cue-words 6 --min-srt-duration-ms 1200
npx lomasub transcribe ./video.mp4 --config options.json
npx lomasub --help

หากหยุดคำสั่งหลังสร้างงานแล้ว งานบนเซิร์ฟเวอร์ยังทำต่อ ใช้ job ID ที่แสดงเพื่อรอผลและดาวน์โหลดภายหลัง:

npx lomasub download <job-id> --output ./video.srt

ค่าเริ่มต้นบันทึก SRT ข้างไฟล์ต้นฉบับ ใช้ --overwrite เมื่อต้องการเขียนทับไฟล์เดิม ใช้ --endpoint เพื่อเปลี่ยน API server (ค่าเริ่มต้น https://api.lomasub.ai)

ใช้ในโค้ด JavaScript

ติดตั้งในโปรเจกต์ด้วย npm install lomasub แล้วเรียก SDK:

import { LomaClient } from 'lomasub';

const client = new LomaClient(); // อ่าน LOMA_API_SECRET_KEY
const result = await client.transcribeFile('./video.mp4', {
  output: './video.srt',
  language: 'th',
  config: { speaker_diarization: true, srt_max_chars: 48 },
  onProgress: event => console.error(event),
});
console.log(result.output_path, result.timing);

SDK รองรับ config ขั้นสูงตาม POST /new-transcribe โดยใช้ชื่อ snake_case เดียวกับ API ส่วน CLI เปลี่ยน _ เป็น - (ไม่รองรับ revise_srt, revise_speakername, srt_revision_backend ทั้งใน SDK และไฟล์ --config) ตัวเลือก boolean มีทั้ง --name และ --no-name ค่า filename, language, duration_seconds อยู่ภายนอก config แพ็กเกจนี้ครอบคลุมงานถอดเสียงและดาวน์โหลดผลต้นฉบับเท่านั้น ไม่มี SDK methods สำหรับจัดการ account หรืออัปโหลดซับไตเติลที่แก้ไข การจัดการ key ทำในหน้าบัญชีของ editor

เมื่อสำเร็จ CLI แสดงสรุปใน stderr เช่น Content: 600.00s | Total: 60.00s | Speed: 10.00x realtime ส่วน stdout ยังคงเป็น path ของ SRT เวลา total รวมการดึงเสียง อัปโหลด รอคิว ประมวลผล และบันทึก SRT ความเร็ว = ความยาวเนื้อหา ÷ เวลารวม

SDK คืนค่า timing: { content_duration_seconds, total_seconds, speed_x } และ output_path เมื่อระบุ output หากไม่ระบุ output จะวัดถึง READY เท่านั้น ความยาวใช้ค่าที่ worker วัดได้ก่อน แล้วจึงใช้ duration_seconds ที่ระบุเอง หากไม่ทราบจะเป็น null (CLI แสดง unknown) คำสั่ง download อย่างเดียวไม่รายงานเวลารวมของงานเดิม

หากจำเป็นต้องเชื่อมต่อระบบด้วย HTTP โดยตรง เช่น ใช้ภาษาอื่นหรือควบคุมขั้นตอนการทำงานเอง สามารถดูขั้นตอนและตัวอย่าง Python ได้ที่ การใช้งานด้วย REST API

เปิดการตรวจแก้คำก่อน alignment ด้วย CLI --promodel pro หรือ SDK config: { promodel: "pro" }