เลือกช่วงเวลาสำคัญ — POST /short-topics

Personal API key ใช้โควตาบัญชีเดียวกับ editor และเข้าถึงเฉพาะงานของเจ้าของ key บัญชีที่ไม่เปิดใช้งานตอบ 403 โควตาไม่พอตอบ 402 ดูวิธีสร้าง key

แต่ละคำขอที่สำเร็จหัก 6 โควตา (ค่า QUOTA_SHORT_TOPICS_COST ของ API) หลังสร้างหัวข้อเสร็จ คำขอที่ประมวลผลล้มเหลวหรือหมดเวลาไม่หักโควตา การตรวจโควตาก่อนเริ่มไม่ได้จองยอดไว้: คำขอที่เริ่มพร้อมกันอาจสำเร็จทั้งคู่และทำให้ยอดติดลบได้ เมื่อยอดไม่พอ คำขอหัวข้อสั้นหรือถอดเสียงครั้งถัดไปจะตอบ 402 ก่อนเริ่มประมวลผล

อัปโหลดไฟล์คำบรรยายของงานที่ถอดเสียงเสร็จแล้ว (result.karaoke.vtt หรือไฟล์ .srt ธรรมดา) ระบบจะส่งเนื้อหาไปให้ LLM ขอ ช่วงเวลาสำคัญ 3, 4 หรือ 6 ช่วงตามจำนวน cue โดยตั้งเป้าความยาวช่วงละ 40-60 วินาที สั้นหรือยาวกว่าเล็กน้อยได้เพื่อให้ประโยคและใจความครบถ้วน พร้อมตั้งชื่อ topic ให้แต่ละช่วง เหมาะกับการนำไปตัดคลิปสั้น การกระจายหัวข้อครอบคลุมเฉพาะเนื้อหาที่เลือกส่งไปวิเคราะห์

POST https://api.lomasub.ai/short-topics

นี่คือ endpoint ฝั่ง client เพียงตัวเดียวที่ช้า: แต่ละคำขอใช้เวลา ประมาณ 20-45 วินาที เพราะต้องรอ LLM ประมวลผล — ตั้งค่า timeout ฝั่ง client อย่างน้อย 120 วินาที โดย API จำกัดเวลาประมวลผลรวมไว้ที่ 100 วินาที (รวมการลองใหม่) เพื่อรองรับ Cloudflare Tunnel

Headers

Header ค่า จำเป็น
Authorization Bearer <API_KEY> — เป็น API key ตัวเดียวกับ endpoint อื่น ต้องระบุ
Content-Type multipart/form-data — curl และ browser ตั้งให้อัตโนมัติ ต้องระบุ

Request Body

ส่งเป็น multipart/form-data มีฟิลด์เดียว

ฟิลด์ ชนิด จำเป็น คำอธิบาย
file file ต้องระบุ ไฟล์ result.karaoke.vtt หรือ .srt — ดาวน์โหลดได้จาก karaoke_vtt_url / srt_url ที่ได้จาก ตรวจสอบสถานะงาน เมื่องานอยู่สถานะ READY

ระบบตรวจรูปแบบไฟล์จากบรรทัดแรก: ขึ้นต้นด้วย WEBVTT จะอ่านแบบ WebVTT (พร้อมตัด timestamp ระดับคำ <hh:mm:ss.ttt> ออก) นอกนั้นอ่านแบบ SRT

ขนาดไฟล์สูงสุด 8 MiB วิเคราะห์ไม่เกิน 2,000 cue ต่อคำขอ หากไฟล์มีมากกว่า 2,000 cue ระบบจะสุ่มตำแหน่งเริ่มจากทุกตำแหน่งที่เลือกได้ด้วยโอกาสเท่ากัน แล้วเลือก 2,000 cue ที่ต่อเนื่องกันเพียงช่วงเดียวก่อนแบ่งส่วน โดยคง timestamp เดิมของไฟล์ คำขอใหม่อาจสุ่มได้คนละช่วง แต่การลองใหม่ภายในคำขอเดียวใช้ช่วงเดิมเสมอ ไม่มีพารามิเตอร์สำหรับกำหนดช่วงหรือ seed

เนื้อหาที่แปลงจาก cue ที่เลือกแล้ว (รวม timestamp) ต้องไม่เกิน 400,000 ตัวอักษร ขีดจำกัดนี้ตรวจหลังสุ่มเลือกช่วง

API อ่านเนื้อหาไฟล์ไม่เกินขีดจำกัดบวกหนึ่ง byte สำหรับตรวจไฟล์ที่ใหญ่เกินไป และจอง slot ก่อนอ่านเนื้อหาและแปลง subtitle เมื่อเต็มจะตอบ 429 พร้อม Retry-After: 30 การรับและ parse multipart ของ framework ยังเกิดก่อนเข้า handler

ตัวอย่าง Request

curl -X POST "https://api.lomasub.ai/short-topics" \
  -H "Authorization: Bearer $LOMA_API_SECRET_KEY" \
  -F "file=@result.karaoke.vtt" \
  --max-time 300

Response — 200 OK

{
  "topics": [
    {
      "topic": "แนวทางการตรวจประเมินผื่น Maculopapular rash โดยแยกตำแหน่งรอยโรคและอาการไข้ร่วมด้วย",
      "start": "00:00:15.872",
      "end": "00:01:03.728"
    },
    {
      "topic": "ลักษณะการลุกลามของผื่นจากศีรษะลงสู่ขาและรอยโรคจุดขาวในปากของโรคหัด",
      "start": "00:02:29.328",
      "end": "00:03:20.320"
    }
  ]
}
ฟิลด์ ชนิด คำอธิบาย
topics array รายการช่วงเวลา สูงสุด 6 ช่วง เรียงตามเวลาเริ่มจากน้อยไปมาก
topics[].topic string ขอชื่อหัวข้อภาษาเดียวกับ transcript ความยาวประมาณ 10-20 คำ
topics[].start string เวลาเริ่ม — HH:MM:SS.mmm หรือ HH:MM:SS (ดูหัวข้อความละเอียดด้านล่าง)
topics[].end string เวลาจบ — รูปแบบเดียวกับ start

ความละเอียดของเวลาและการ snap ขอบ cue

ระบบจำกัดเวลาที่ LLM เลือกให้อยู่ในส่วนที่ส่งไปวิเคราะห์ แล้ว snap ไปยังขอบของ cue จริงในไฟล์ที่อัปโหลดที่ใกล้ที่สุดภายใน 2 วินาที โดย start snap ไปหาเวลาเริ่มของ cue และ end snap ไปหาเวลาจบของ cue หากไม่มีขอบ cue ภายใน 2 วินาทีจะเก็บค่านั้นไว้ การเริ่มและจบตรงประโยคเป็นคำแนะนำใน prompt ไม่ใช่สิ่งที่โค้ดรับประกัน

ความละเอียดขึ้นกับไฟล์ต้นทาง: ถ้ามี timestamp ใดในไฟล์ที่มีเศษมิลลิวินาทีไม่เป็นศูนย์ ระบบจะคืนค่าเป็น HH:MM:SS.mmm แต่ถ้าทุก timestamp เป็นวินาทีถ้วนทั้งไฟล์ จะคืนเป็น HH:MM:SS

ไฟล์ต้นทาง ตัวอย่าง timestamp ผลลัพธ์
result.karaoke.vtt 00:08:39.012 00:08:39.012
result.srt 00:00:00,128 00:00:00.128
.srt ที่เป็นวินาทีถ้วน 00:00:10,000 00:00:10

แบ่งวิเคราะห์ขนานกันตามจำนวน cue ที่เลือก:

จำนวน cue ที่เลือก จำนวน LLM calls พร้อมกัน จำนวนช่วงที่ขอต่อ call จำนวนช่วงที่ขอรวม
1-99 1 3 3
100-300 2 2 4
301-2,000 3 2 6

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

จำนวนที่ขอเป็นคำแนะนำใน prompt ระบบยอมรับผลที่มีน้อยกว่าจำนวนที่ขอและจำกัดผลรวมไว้ไม่เกิน 6 ช่วงเสมอ แม้คำขอนั้นจะขอเพียง 3 หรือ 4 ช่วง ถ้า LLM ตอบเกิน 6 จะคัดให้กระจายโดยเก็บช่วงแรกและช่วงสุดท้ายไว้ ความยาว 40-60 วินาที การไม่ซ้อนทับกัน ความสมบูรณ์ของประโยค และความยาวชื่อหัวข้อไม่ได้ตรวจบังคับด้วยโค้ด ระบบรับประกันว่า start < end และเวลาอยู่ภายในส่วนที่วิเคราะห์ คำขอสำเร็จยังหักโควตาตามค่าคงที่ที่ตั้งไว้ (ค่าเริ่มต้น 6) ไม่ขึ้นกับจำนวนหัวข้อที่คืน

ข้อผิดพลาดที่อาจพบ

สถานะ สาเหตุ ตัวอย่างข้อความ
401 Unauthorized ไม่มีหรือ API key ไม่ถูกต้อง —
402 Payment Required โควตาที่ใช้ได้ไม่พอสำหรับคำขอใหม่ รวมกรณียอดติดลบ "โควตาไม่พอ — เหลือ -6 ต้องใช้ 6 ..."
413 Payload Too Large ไฟล์ใหญ่เกิน 8 MB "subtitle upload is too large"
422 Unprocessable Entity ไม่มีฟิลด์ file ใน multipart body ตอบเป็น list ตามรูปแบบ FastAPI
422 Unprocessable Entity ไฟล์ไม่ใช่ WebVTT/SRT, ไม่ใช่ UTF-8, ไม่มี cue หรือเนื้อหายาวเกินกำหนด "file must be a webvtt or srt transcript"
429 Too Many Requests มีคำขอกำลังประมวลผลอยู่เต็มจำนวน (มากกว่า 4 คำขอพร้อมกัน) หรือ LLM จำกัดอัตราการเรียก — header Retry-After: 30 "short-topics is busy, retry later"
502 Bad Gateway เรียก LLM ไม่สำเร็จ หรือ LLM ตอบกลับในรูปแบบที่ใช้ไม่ได้ "llm returned no usable topics"
503 Service Unavailable ระบบยังไม่ได้ตั้งค่า OPENROUTER_API_KEY "short-topics is not configured"
504 Gateway Timeout LLM หรือการประมวลผลรวมใช้เวลานานเกินกำหนด — ไม่หักโควตาเมื่อหมดเวลาประมวลผล "llm request timed out" หรือ "short-topics request timed out"

เมื่อเรียกผ่าน Cloudflare อาจได้รับข้อความ error ทั่วไปแทน JSON สำหรับสถานะ 502 / 504 ให้ตรวจ HTTP status ก่อนอ่าน detail โดยสถานะ 504 จากการหมดเวลาประมวลผลจะไม่หักโควตา

results matching ""

    No results matching ""