Tạo job và lấy clip qua REST API
Đăng nhập lấy token, gửi một link vào POST /api/process, rồi đọc clip từ GET /api/status/{job_id}. Dashboard cũng dùng đúng các route này.
Trước khi gọi API
- Một tài khoản VimeoClip có mật khẩu. Member gọi được /api/process, /api/uploads và đọc job của chính mình.
- Đủ credit. Tài khoản mới có thể có 0 credit, khi đó POST /api/process trả 402.
- Máy chủ có GEMINI_API_KEY hoặc LLM_BASE_URL. Nếu không, gửi key của bạn trong header X-Gemini-Key.
- Bạn sở hữu nội dung hoặc có quyền xử lý nó. Request phải có acknowledged: true.
Lấy token
POST /api/auth/login trả access_token. Gửi token đó trong header Authorization: Bearer ở mọi request sau. Token hết hạn sau 30 ngày, và đổi mật khẩu làm token cũ mất hiệu lực.
BASE=http://localhost:8000
curl -s -X POST "$BASE/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"YOUR_PASSWORD"}'{
"ok": true,
"access_token": "eyJhbGciOi...",
"token_type": "bearer",
"user": { "...": "..." }
}Tạo job từ một link
Cần url và acknowledged. Mọi field khác là tuỳ chọn. Với cùng Idempotency-Key, gửi lại request sẽ nhận lại câu trả lời cũ thay vì tạo job thứ hai.
curl -s -X POST "$BASE/api/process" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: podcast-42" \
-d '{
"url": "https://www.youtube.com/watch?v=VIDEO_ID",
"acknowledged": true,
"target_clips": 5,
"clip_min_seconds": 30,
"clip_max_seconds": 90,
"output_format": "vertical",
"captions": true,
"auto_hook": true,
"webhook_url": "https://hooks.example.com/openshorts",
"webhook_secret": "change-me"
}'{ "job_id": "2f6c0a1e-...", "status": "queued" }Tạo job từ file
Gửi file trong một request multipart, hoặc đặt chỗ qua POST /api/uploads rồi PUT dữ liệu thô. Giới hạn file mặc định là 2048 MB (MAX_FILE_SIZE_MB). Response của POST /api/uploads trả upload_id, upload_url, max_mb và expires_in.
# Tải file trong một request multipart
curl -s -X POST "$BASE/api/process" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@video.mp4" \
-F "acknowledged=true"
# Hoặc đặt chỗ, PUT dữ liệu, rồi truyền upload_id
curl -s -X POST "$BASE/api/uploads" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"filename":"video.mp4"}'
curl -T video.mp4 "$BASE/api/uploads/UPLOAD_ID" \
-H "Authorization: Bearer $TOKEN"
curl -s -X POST "$BASE/api/process" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"upload_id":"UPLOAD_ID","acknowledged":true}'Các field hay dùng của POST /api/process
Gửi JSON, hoặc gửi cùng tên field dưới dạng form khi tải file lên.
| Field | Giá trị | Ý nghĩa |
|---|---|---|
| url | Chuỗi | Link video công khai. Dùng url, file hoặc upload_id. |
| upload_id | Chuỗi | Slot đã tải file lên từ POST /api/uploads. |
| acknowledged | true | Xác nhận bạn có quyền xử lý nội dung. Bắt buộc. |
| target_clips | 1 đến 30 | Số clip mong muốn. Có thể nhận ít hơn nếu video không đủ đoạn tốt. |
| clip_min_seconds | 0 đến 895 | Độ dài tối thiểu của clip. |
| clip_max_seconds | 10 đến 900 | Độ dài tối đa của clip. |
| analysis_start_seconds, analysis_end_seconds | Số giây, gửi cùng nhau | Chỉ phân tích một đoạn của nguồn. Credit tính theo đoạn này. |
| output_format | auto, vertical, horizontal, square, portrait | Tỉ lệ clip. |
| layouts | auto, split, screencast, speaker_cut, punch_in, none | Mảng JSON hoặc chuỗi cách nhau bằng dấu phẩy. |
| captions | true, false | Có đốt phụ đề vào clip hay không. |
| caption_preset | Ví dụ auto, tiktok, reels, minimal | Kiểu phụ đề. |
| source_language, caption_language | Mã ISO 639-1 hoặc auto | Ngôn ngữ nói và ngôn ngữ phụ đề. |
| auto_hook, auto_hook_style | true; classic, dark, yellow, red, outline, outline_yellow | Dòng hook trên clip. REST chỉ bật khi bạn gửi auto_hook: true. |
| moment_hint | Chuỗi | Chủ đề hoặc câu nói bạn muốn ưu tiên. |
| clip_workflow | best, coverage, find | find cần moment_hint. coverage cần clip_lenses là content. |
| clip_lenses | arc, chunk, stitch, seam | Chuỗi cách nhau bằng dấu phẩy. Thêm lens là thêm lần gọi AI. |
| test_mode | true | Chạy toàn bộ phần phân tích, bỏ qua render. Chi phí AI như job thật và không gửi webhook. |
| force_low_quality | true | Chạy tiếp sau cảnh báo độ phân giải thấp. |
| webhook_url, webhook_secret | Chuỗi | Nhận POST khi job kết thúc. |
Bảng này chưa phải toàn bộ. process_endpoint trong backend/app.py còn nhiều field về kiểu phụ đề và hook.
Đọc trạng thái
status là queued, processing, completed, failed hoặc cancelled. Polling mỗi 30 đến 60 giây là đủ. Thêm summary=true để nhận bản gọn gồm status, generation, progress, eta_seconds, error và clip_count.
# Response đầy đủ
curl -s "$BASE/api/status/$JOB_ID" -H "Authorization: Bearer $TOKEN"
# Response gọn để polling
curl -s "$BASE/api/status/$JOB_ID?summary=true" -H "Authorization: Bearer $TOKEN"{
"status": "completed",
"generation": 1,
"progress": 100,
"eta_seconds": null,
"logs": ["..."],
"result": {
"clips": [
{
"start": 312.4,
"end": 368.9,
"video_url": "/videos/JOB_ID/FILE_NAME.mp4",
"predicted_score": 81,
"video_title_for_youtube_short": "...",
"video_description_for_tiktok": "...",
"video_description_for_instagram": "..."
}
]
},
"settings": { "...": "..." },
"error": null
}Đọc và tải clip
result.clips xếp clip mạnh nhất lên đầu. video_url là đường dẫn trên cùng host. predicted_score là điểm thô dùng để xếp hạng. Đường dẫn /videos cần token của chủ job.
# Đường dẫn clip, clip mạnh nhất lên đầu
curl -s "$BASE/api/status/$JOB_ID" -H "Authorization: Bearer $TOKEN" \
| jq -r '.result.clips[].video_url'
# Một clip. /videos cần cùng token.
curl -L -H "Authorization: Bearer $TOKEN" \
-o clip-1.mp4 "$BASE/videos/$JOB_ID/FILE_NAME.mp4"
# Mọi clip chính trong một file ZIP. indices=0,2 để chọn clip cụ thể.
curl -L -H "Authorization: Bearer $TOKEN" \
-o clips.zip "$BASE/api/jobs/$JOB_ID/download-all"Credit được giữ cho từng job
Khi job được nhận, reserve_job_credits giữ 1 credit cho mỗi phút độ dài nguồn, làm tròn lên, tối thiểu 1. Nếu bạn gửi analysis_start_seconds và analysis_end_seconds, độ dài tính theo đoạn đó. Nếu máy chủ chưa đo được độ dài lúc nhận job, nó giữ 1 credit.
Khi job xong, số credit được chốt theo độ dài thật. Job failed hoặc cancelled được hoàn lại. Quy tắc này áp dụng cho cả tài khoản admin.
Tài khoản đang ở plan free sẽ có watermark đốt vào clip.
Khi thiếu credit
POST /api/process trả 402 và không tạo job.
{
"detail": {
"error": "quota_exceeded",
"minutes_required": 42,
"minutes_remaining": 10,
"message": "Insufficient credits (10 available, 42 required). Please add credits or upgrade your plan."
}
}Mã trả về cần xử lý
Lỗi trả JSON có field detail.
| Mã | Khi nào | Nên làm gì |
|---|---|---|
| 200, needs_confirmation | Nguồn thấp hơn ngưỡng QUALITY_GATE_MIN_HEIGHT, mặc định 720p. Chưa tạo job. | Hỏi người dùng, rồi gửi lại với force_low_quality: true. |
| 400 | Thiếu nguồn, thiếu acknowledged, giá trị ngoài khoảng, webhook_url không hợp lệ, hoặc link ngắn hơn MIN_SOURCE_SECONDS (mặc định 45 giây). | Đọc detail và sửa request. |
| 401 | Thiếu token hoặc token không hợp lệ. | Đăng nhập lại. |
| 402 | Không đủ credit. | Nạp thêm credit hoặc nhờ admin cấp. |
| 403 | Route chỉ dành cho admin, member chọn endpoint AI riêng, hoặc Origin của trình duyệt không nằm trong danh sách cho phép. | Dùng tài khoản admin, hoặc nhờ quản trị viên thêm origin vào danh sách cho phép. |
| 404 | Job không tồn tại hoặc không thuộc tài khoản này. | Kiểm tra job_id và tài khoản. |
| 503 | Máy chủ đang bàn giao job khi cập nhật. | Thử lại sau thời gian trong Retry-After. |
Câu hỏi thường gặp
Có. Tạo khóa osk_ ở trang Truy cập API và gửi trong header Authorization: Bearer hoặc X-API-Key. Khóa mang đúng quyền và credit của tài khoản, không hết hạn, và thu hồi được bất cứ lúc nào. Token phiên từ POST /api/auth/login vẫn dùng được, nhưng chỉ sống 30 ngày.
Tài khoản member chỉ gọi được các route đã được duyệt cho member. Sửa phụ đề, cắt lại clip và đăng bài cần tài khoản admin.
Về chi phí AI thì không. Transcript, chấm điểm và các bước kiểm tra vẫn chạy. Job chỉ bỏ qua bước render.
Gọi GET /api/me với token. Response có credits_balance, plan và role.
Bỏ vòng lặp polling
Truyền webhook_url và nhận một POST có chữ ký khi job kết thúc.
Video minh hoạ (stock), không phải kết quả của VimeoClip · Storyblocks




