เอกสารอ้างอิง Video Translation Agent API

เอกสารนี้ใช้สำหรับ Agent บริการแบ็กเอนด์ และสคริปต์ที่ต้องการทำงานแปลวิดีโอของ SoulDub แบบอัตโนมัติ สำหรับการแปลทั่วไป ให้ใช้สคริปต์ helper ที่เผยแพร่ก่อน และใช้เอกสารนี้เมื่อแก้ไขปัญหา API การยืนยันตัวตน ความเป็นไอดีเอ็มโพเทนต์ การจำกัดอัตรา การดาวน์โหลดผลลัพธ์ หรือรหัสข้อผิดพลาด

• URL พื้นฐานของ API คือ https://xxx.com/api/v1
• เส้นทางภายนอกทั้งหมดอยู่ใต้ /api/v1/...
• ทุก endpoint ต้องใช้ Agent API key
• การอัปโหลดไบนารีใช้ presigned URL โดยไม่ส่ง API key ไปกับคำขอ PUT
• URL ของ media gateway ใช้ดาวน์โหลดโดยไม่ต้องส่ง API key
• การดาวน์โหลดคำบรรยายยังเป็น Agent API และต้องใช้ API key
• การสร้างงานและการแปลซ้ำต้องมี Idempotency-Key ที่คงที่
• อย่าบันทึก API key, presigned URL หรือพารามิเตอร์ลายเซ็นไว้ใน log และไฟล์สถานะ
• เมื่อได้รับ 429 ให้รอตามค่า Retry-After และเคารพขีดจำกัดการทำงานพร้อมกัน
• เมื่อ URL ชั่วคราวหมดอายุ ให้ขอ URL ใหม่จาก endpoint ผลลัพธ์

1. POST /video-uploads/initiate
2. POST /video-uploads/presign-part
3. PUT {presignedUrl}
4. POST /video-uploads/complete
5. POST /video-translations
6. GET /video-translations/{taskId}
7. GET /video-translations/{taskId}/results
8. GET /video-translations/{taskId}/results/files/{variant}
9. GET /video-translations/{taskId}/results/subtitles/{variant}

การแปลซ้ำใช้ POST /video-translations/{existingTaskId}/retranslate

Authorization: Bearer ${AGENT_API_KEY}
X-API-Key: ${AGENT_API_KEY}
Content-Type: application/json
Accept: application/json

X-Request-Id เป็นตัวเลือก หากระบุค่าต้องมีความยาว 8 ถึง 64 ตัวอักษร เซิร์ฟเวอร์จะคืน request id สุดท้ายใน response header

{
  "code": 0,
  "message": "ok",
  "data": {}
}

เวลาตรวจสอบปัญหา ให้ดู HTTP status, error.code, error.details และ X-Request-Id ตามลำดับ

เริ่มอัปโหลด ขอ presigned URL ส่งไบต์วิดีโอ และยืนยันการอัปโหลดตามลำดับ

POST /video-uploads/initiate
POST /video-uploads/presign-part
PUT {presignedUrl}
POST /video-uploads/complete

• filename ต้องเป็นชื่อไฟล์ .mp4
• contentType ต้องเป็น video/mp4
• fileSizeBytes ต้องมากกว่า 0 และไม่เกินขีดจำกัดบัญชี
• presignedUrl ใช้เฉพาะการอัปโหลดปัจจุบันและห้ามบันทึกใน log
• คำขอ PUT ไม่ต้องใส่ Authorization หรือ X-API-Key
• ตรวจสอบ data.success, data.status และ data.fileId หลังการยืนยัน

POST /video-translations
Idempotency-Key: ${UNIQUE_IDEMPOTENCY_KEY}

Request ต้องมี fileId, videoDurationSeconds, sourceLanguage และ targetLanguage โดย sourceLanguage รองรับ auto แต่ targetLanguage ห้ามเป็น auto

• เก็บ taskId, fileId, creditsConsumed และ Idempotency-Key
• คำขอที่ใช้ key และ body เดิมซ้ำจะไม่ถูกเรียกเก็บเครดิตซ้ำ
• ใช้ key เดิมกับ body ต่างกันจะได้ IDEMPOTENCY_KEY_REUSED
• หากคำขอยังประมวลผลอยู่จะได้ IDEMPOTENCY_REQUEST_IN_PROGRESS
• หาก timeout ให้ลองใหม่ด้วย body และ key เดิม

GET /video-translations/{taskId}

สถานะอาจเป็น pending, processing, completed, failed หรือ cancelled

• ตรวจสอบครั้งแรกประมาณ 2 วินาทีหลังสร้างงาน
• เพิ่มช่วงเวลาตรวจสอบเป็น 2s → 5s → 10s → 20s → 30s
• เมื่อได้ 429 ให้รอตาม Retry-After
• เมื่อได้ 5xx ให้ใช้ exponential backoff พร้อม timeout รวม
• หยุด polling เมื่อสถานะเป็น completed, failed หรือ cancelled

GET /video-translations/{taskId}/results?expiresIn=600
GET /video-translations/{taskId}/results/files/{variant}?expiresIn=600
GET /video-translations/{taskId}/results/subtitles/{variant}

• video: วิดีโอ MP4 ที่รวมเสร็จแล้ว
• vocal: ไฟล์เสียงพูด WAV
• background: ไฟล์เสียงพื้นหลัง WAV
• full: ไฟล์เสียงพูดที่สังเคราะห์รวมทั้งหมด
• source, translated และ bilingual: ไฟล์คำบรรยาย SRT
• URL ที่หมดอายุให้เรียก endpoint ผลลัพธ์ซ้ำเพื่อขอ URL ใหม่

POST /video-translations/{existingTaskId}/retranslate
Idempotency-Key: ${UNIQUE_IDEMPOTENCY_KEY}

งานที่มีสถานะ completed, failed หรือ cancelled สามารถแปลซ้ำได้ การแปลซ้ำจะสร้างงานใหม่และอยู่ภายใต้การคิดเครดิตและขีดจำกัดการทำงานพร้อมกัน

สามารถเก็บ apiBase, fileId, uploadId, key, taskId, ภาษา และ status เพื่อกลับมาทำงานต่อได้

• ห้ามเก็บ Agent API key
• ห้ามเก็บ presigned URL ระยะยาว
• ห้ามเก็บ temporary media URL
• ใช้ taskId เพื่อตรวจสอบสถานะและขอผลลัพธ์ใหม่
• ใช้ uploadId และ key เพื่อสร้าง URL ของพาร์ตที่ยังไม่เสร็จใหม่

• UNAUTHORIZED, API_KEY_INVALID, API_KEY_EXPIRED และ API_KEY_REVOKED เป็นข้อผิดพลาดด้านการยืนยันตัวตน
• RATE_LIMITED และ CONCURRENCY_LIMIT_REACHED ให้รอแล้วลองใหม่
• INSUFFICIENT_CREDITS, INVALID_REQUEST, INVALID_LANGUAGE และ FILE_TOO_LARGE ให้ตรวจสอบข้อมูลนำเข้า
• TASK_NOT_COMPLETED และ RESULT_NOT_READY ให้รอการประมวลผล
• TASK_NOT_FOUND, SUBTITLE_NOT_FOUND และ FINAL_VIDEO_EXPIRED ให้ตรวจสอบรายละเอียดก่อนเรียกใหม่
• ข้อผิดพลาด 5xx ใช้ exponential backoff ที่มีขีดจำกัด

• ใช้ Base URL, Agent API key และ endpoint ที่ระบุในเอกสารเท่านั้น
• อย่า cache หรือเก็บ presigned URL และ temporary media URL ระยะยาว
• อย่าเขียน API key หรือ URL ดาวน์โหลดลงใน log หรือบริบทการสนทนา
• เมื่อ URL ดาวน์โหลดหมดอายุ ให้เรียก endpoint ผลลัพธ์เพื่อรับ URL ใหม่