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

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

กระบวนการทั้งหมดมี 4 ขั้นตอน ได้แก่ ขอ URL สำหรับอัปโหลด → อัปโหลดไฟล์ → สร้างงานซับไตเติล → ตรวจสอบสถานะและดาวน์โหลดผลลัพธ์

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น คุณต้องมีสิ่งต่อไปนี้

• API key สำหรับเรียก Loma Sub API
• Python 3
• ไฟล์เสียงหรือวิดีโอในเครื่อง ตัวอย่างนี้ใช้ไฟล์ audio.mp3

หากใช้ไฟล์ชนิดอื่น ให้เปลี่ยนชื่อไฟล์และ MIME type ในตัวอย่าง Python ให้ตรงกับไฟล์จริง เช่นใช้ video/mp4 สำหรับไฟล์ MP4

เก็บ API key ไว้ในตัวแปรสภาพแวดล้อมเพื่อไม่ให้เขียนรหัสลับลงในโปรแกรมโดยตรง

export LOMA_API_SECRET_KEY="<your-api-key>"

ขั้นตอนที่ 1 — ขอ URL สำหรับอัปโหลดไฟล์

เรียก POST /presigned-url โดยส่งชื่อไฟล์และ MIME type ระบบจะคืนค่าที่สำคัญดังนี้

• upload_url — URL ชั่วคราวสำหรับอัปโหลดไฟล์
• headers — HTTP headers ที่ต้องใช้ตอนอัปโหลด
• source_url — URL ของไฟล์หลังจากอัปโหลดสำเร็จ

ตัวอย่าง request body:

{
  "filename": "audio.mp3",
  "content_type": "audio/mpeg"
}

ตัวอย่าง response:

{
  "method": "PUT",
  "upload_url": "https://...presigned-upload-url...",
  "headers": {
    "Content-Type": "audio/mpeg",
    "x-amz-acl": "public-read"
  },
  "source_url": "https://.../tmpupload/example.mp3",
  "expires_in_seconds": 86400
}

ขั้นตอนที่ 2 — อัปโหลดไฟล์

ส่งไฟล์ไปยัง upload_url ด้วย HTTP method และ headers ที่ได้รับจากขั้นตอนก่อนหน้า โดยต้องส่ง headers ให้ครบและมีค่าตรงกับ response

การอัปโหลดไปยัง upload_url ไม่ต้องส่ง API key หรือ Authorization header เพราะสิทธิ์สำหรับอัปโหลดรวมอยู่ใน URL แล้ว เมื่อคำขออัปโหลดสำเร็จจึงนำ source_url ไปใช้สร้างงานซับไตเติลได้

ขั้นตอนที่ 3 — สร้างงานซับไตเติล

เรียก POST /new-transcribe พร้อม source_url จากขั้นตอนที่ 1 และภาษาของเสียง

{
  "source_url": "https://.../tmpupload/example.mp3",
  "language": "th"
}

ระบบจะตอบกลับ job_id สำหรับใช้ติดตามงาน

{
  "job_id": "0b8a4f3e-6c1d-4a9b-9f2e-7d5c3b1a8e64",
  "status_url": "https://api.lomasub.ai/status?job_id=0b8a4f3e-6c1d-4a9b-9f2e-7d5c3b1a8e64",
  "state": "QUEUED"
}

ขั้นตอนที่ 4 — ตรวจสอบสถานะและดาวน์โหลดผลลัพธ์

เรียก GET /status พร้อม job_id เป็นระยะ แนะนำให้เรียกประมาณทุก 1 วินาที

• เมื่อ state เป็น READY หมายถึงงานเสร็จสมบูรณ์และดาวน์โหลดผลลัพธ์ได้
• เมื่อ state เป็น FAILED หมายถึงงานล้มเหลว ให้ตรวจสอบ failed_stage และ error
• สถานะอื่นหมายถึงงานยังอยู่ในคิวหรือกำลังประมวลผล

เมื่อสถานะเป็น READY response จะมี URL สำหรับดาวน์โหลดผลลัพธ์

{
  "job_id": "0b8a4f3e-6c1d-4a9b-9f2e-7d5c3b1a8e64",
  "state": "READY",
  "srt_url": "https://...presigned.../result.srt?...",
  "vtt_url": "https://...presigned.../result.vtt?...",
  "compact_url": "https://...presigned.../result.compact.txt?..."
}

URL ดาวน์โหลดเป็น presigned URL ที่มีอายุจำกัด หาก URL หมดอายุ ให้เรียก GET /status ด้วย job_id เดิมอีกครั้งเพื่อรับ URL ชุดใหม่

ตัวอย่าง Python แบบครบวงจร

ตัวอย่างต่อไปนี้ใช้เฉพาะ Python standard library เพื่อขอ URL อัปโหลด อัปโหลดไฟล์ สร้างงาน ตรวจสอบสถานะ และดาวน์โหลดผลลัพธ์ที่ระบบส่งกลับมา

import json
import os
import time
import urllib.parse
import urllib.request

API_BASE = "https://api.lomasub.ai"
API_KEY = os.environ["LOMA_API_SECRET_KEY"]
INPUT_FILE = "audio.mp3"
CONTENT_TYPE = "audio/mpeg"


def call_api(path, payload=None):
    data = None
    method = "GET"
    if payload is not None:
        data = json.dumps(payload).encode("utf-8")
        method = "POST"

    request = urllib.request.Request(
        f"{API_BASE}{path}",
        data=data,
        method=method,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.loads(response.read())


# 1) ขอ presigned URL สำหรับอัปโหลด
upload = call_api(
    "/presigned-url",
    {
        "filename": os.path.basename(INPUT_FILE),
        "content_type": CONTENT_TYPE,
    },
)

# 2) อัปโหลดไฟล์ด้วย method และ headers ที่ API กำหนด
with open(INPUT_FILE, "rb") as audio_file:
    upload_request = urllib.request.Request(
        upload["upload_url"],
        data=audio_file.read(),
        method=upload["method"],
        headers=upload["headers"],
    )
    with urllib.request.urlopen(upload_request, timeout=300):
        pass

# 3) สร้างงานซับไตเติลด้วย source_url ของไฟล์ที่อัปโหลดแล้ว
job = call_api(
    "/new-transcribe",
    {
        "source_url": upload["source_url"],
        "language": "th",
    },
)
job_id = job["job_id"]
print("job created:", job_id)

# 4) ตรวจสอบสถานะประมาณทุก 1 วินาที
query = urllib.parse.urlencode({"job_id": job_id})
while True:
    status = call_api(f"/status?{query}")
    state = status["state"]
    print("state:", state)

    if state == "READY":
        break
    if state == "FAILED":
        raise RuntimeError(
            f"{status.get('failed_stage')}: {status.get('error')}"
        )

    time.sleep(1)

# 5) ดาวน์โหลดผลลัพธ์ทุกชนิดที่มีใน response
outputs = {
    "srt_url": "result.srt",
    "vtt_url": "result.vtt",
    "compact_url": "result.compact.txt",
}
for url_field, output_name in outputs.items():
    if url_field in status:
        urllib.request.urlretrieve(status[url_field], output_name)
        print("saved:", output_name)

เมื่อโปรแกรมทำงานสำเร็จ จะได้ไฟล์ result.srt และผลลัพธ์ประกอบอย่าง result.vtt หรือ result.compact.txt ตาม URL ที่ API ส่งกลับมา