⚡ API REFERENCE v1

API Docs - Tạo Video Render

Tài liệu tích hợp duy nhất cho API Tạo Video Render (Scope: render:create). Cột bên phải là tổng quan endpoint và mẫu request/response. Cột bên trái là chi tiết cấu trúc các trường và mã lỗi.

Mục chi tiết:
HeaderBắt buộcMô tảVí dụ
AuthorizationCóĐịnh dạng: Bearer <raw_token>. Token phải active, chưa hết hạn, có scope render:create.Bearer rk_abc123...
Idempotency-KeyCóKhóa duy nhất cho mỗi nghiệp vụ. Gửi lại cùng key + cùng token thì API trả về job cũ.lesson-42-lineup-001
Content-TypeCóPhải là application/jsonapplication/json

Root object gồm 3 field chính: options, content, callbackUrl.

2.1 Root fields

FieldBắt buộcKiểuMô tả
optionsKhôngobjectTùy chọn cấu hình render (có default).
contentCóobjectNội dung cần render. Bắt buộc có lines.
callbackUrlKhôngstring | nullWebhook nhận kết quả (được kiểm tra an toàn SSRF).

2.2 options

FieldBắt buộcGiá trị hợp lệDefault
options.templateKhôngkaraoke-scroll-continuouskaraoke-scroll-continuous (Tự động mặc định ngầm)
options.aspectRatioKhông16:9 | 9:16 | 1:1 | 4:516:9
options.resolutionKhông720p | 1080p | 4k1080p
options.speedKhôngslow | normal | fastnormal
options.themeKhôngobjectcó default
options.backgroundImageKhôngobject | nullnull
options.audioKhôngobject | nullnull
options.brandingKhôngobject | nullnull

2.3 options.theme

FieldBắt buộcGiá trị hợp lệDefault
theme.presetKhôngdark | light | branddark
theme.highlightStyleKhôngcolor-change | bold-scale-pop | underline-sweepcolor-change
theme.highlightColorKhông#ffd700 | #60a5fa | #34d399 | #f472b6 | #fb923c | #a78bfa#ffd700
theme.focusStyleKhôngnone | soft-glow | side-bars | subtle-bandnone
theme.highlightIntensityKhôngSố trong [0, 1]0.85
theme.transitionKhôngscroll-only | scroll-fade | slide-horizontalscroll-only

2.4 options.backgroundImage

FieldBắt buộcKiểu/Giá trịDefault
backgroundImage.urlKhôngURL hợp lệ | nullnull
backgroundImage.fitKhôngcover | contain | fill | blur-fillcover
backgroundImage.overlayOpacityKhôngSố trong [0, 1]0.4

2.5 options.audio

FieldBắt buộcKiểu/Giá trịDefault
audio.backgroundUrlKhôngURL hợp lệ | nullnull
audio.backgroundVolumeKhôngSố trong [0, 1]0.3
audio.fadeInMsKhôngSố nguyên >= 00
audio.fadeOutMsKhôngSố nguyên >= 00

2.6 options.branding

FieldBắt buộcKiểu/Giá trịDefault
branding.logoUrlKhôngURL hợp lệ | nullnull
branding.logoPositionKhôngtop-left | top-right | bottom-left | bottom-righttop-right
branding.colors.primaryKhôngHex màu #RRGGBBkhông set
branding.colors.accentKhôngHex màu #RRGGBBkhông set

2.7 content

FieldBắt buộcKiểu/Giá trịDefault
content.annotationTypeKhôngruby | romanization-line | none | autoauto
content.linesCóMảng >= 1 phần tửkhông có

2.8 content.lines[]

FieldBắt buộcKiểu/Giá trịGhi chú
line.textCóstring, độ dài >= 1Nội dung câu chính
line.translationKhôngstring | nullBản dịch
line.segmentsKhôngArray<{text, reading?}> | nullDùng cho ruby/furigana
line.romanizationKhôngstring | nullPhiên âm dòng
line.startMsKhôngSố nguyên >= 0 | nullMốc bắt đầu
line.endMsKhôngSố nguyên >= 0 | nullMốc kết thúc
line.wordsKhôngArray<{text,startMs,endMs}> | nullTimeline theo từng từ
FieldÝ nghĩa
jobIdID duy nhất của render job
statusTrạng thái hiện tại: queued | processing | completed | failed
statusUrlĐường dẫn tương đối để kiểm tra trạng thái job
error.codeMã lỗi máy đọc để retry/phân nhánh
error.messageThông điệp lỗi chi tiết cho debug
HTTPerror.codeKhi nào xảy raHướng xử lý đề xuất
400missing_idempotency_keyThiếu Idempotency-KeySinh key duy nhất theo nghiệp vụ rồi gửi lại
400invalid_inputBody sai schema/enum/rangeSửa payload theo bảng field ở phần 2
400invalid_callback_urlcallbackUrl không đạt chính sách an toànDùng webhook HTTPS hợp lệ
401(không cố định)Token rỗng/sai/hết hạn/revokedTạo token mới hoặc gia hạn token
403(không cố định)Thiếu scope render:create hoặc owner không activeCập nhật scope/tài khoản
429(không cố định)Vượt giới hạn render theo ngàyRetry ngày mới hoặc tăng hạn mức
500internal_errorLỗi hệ thốngRetry có backoff, ghi log request
  • Luôn sinh Idempotency-Key theo business event, không dùng timestamp ngẫu nhiên.
  • Validate payload phía client trước khi gọi API để giảm thiểu lỗi 400.
  • Retry theo exponential backoff cho 429/500, không retry tự động cho lỗi 400.
  • Lưu token trong secret manager an toàn, không gửi trực tiếp từ trình duyệt public.
  • Nếu dùng callbackUrl, hãy kiểm tra chữ ký webhook ở backend nhận callback.
POST/api/v1/render
● Active Endpoint

Tạo một render job mới cho video karaoke/teleprompter dựa trên schema và các lựa chọn theme, audio, branding.

Xác thực:Bearer Token
Scope:render:create
Idempotency:Bắt buộc Key
Format:application/json
Mẫu Yêu Cầu & Phản Hồi
cURL Request Example
curl -X POST "https://your-domain.com/api/v1/render" \
  -H "Authorization: Bearer rk_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: render-lesson-001" \
  -H "Content-Type: application/json" \
  --data @payload.json