Đến nội dung chính
[ REST API ]

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.

Request · bash
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"}'
Response · json
{
  "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.

Request · bash
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"
  }'
Response · json
{ "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.

File · bash
# 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.

FieldGiá trịÝ nghĩa
urlChuỗiLink video công khai. Dùng url, file hoặc upload_id.
upload_idChuỗiSlot đã tải file lên từ POST /api/uploads.
acknowledgedtrueXác nhận bạn có quyền xử lý nội dung. Bắt buộc.
target_clips1 đến 30Số clip mong muốn. Có thể nhận ít hơn nếu video không đủ đoạn tốt.
clip_min_seconds0 đến 895Độ dài tối thiểu của clip.
clip_max_seconds10 đến 900Độ dài tối đa của clip.
analysis_start_seconds, analysis_end_secondsSố giây, gửi cùng nhauChỉ phân tích một đoạn của nguồn. Credit tính theo đoạn này.
output_formatauto, vertical, horizontal, square, portraitTỉ lệ clip.
layoutsauto, split, screencast, speaker_cut, punch_in, noneMảng JSON hoặc chuỗi cách nhau bằng dấu phẩy.
captionstrue, falseCó đốt phụ đề vào clip hay không.
caption_presetVí dụ auto, tiktok, reels, minimalKiểu phụ đề.
source_language, caption_languageMã ISO 639-1 hoặc autoNgôn ngữ nói và ngôn ngữ phụ đề.
auto_hook, auto_hook_styletrue; classic, dark, yellow, red, outline, outline_yellowDòng hook trên clip. REST chỉ bật khi bạn gửi auto_hook: true.
moment_hintChuỗiChủ đề hoặc câu nói bạn muốn ưu tiên.
clip_workflowbest, coverage, findfind cần moment_hint. coverage cần clip_lenses là content.
clip_lensesarc, chunk, stitch, seamChuỗi cách nhau bằng dấu phẩy. Thêm lens là thêm lần gọi AI.
test_modetrueChạ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_qualitytrueChạy tiếp sau cảnh báo độ phân giải thấp.
webhook_url, webhook_secretChuỗiNhậ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.

Request · bash
# 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"
Response rút gọn · json
{
  "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.

Bash · bash
# Đườ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.

402 · json
{
  "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àoNên làm gì
200, needs_confirmationNguồ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.
400Thiế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.
401Thiếu token hoặc token không hợp lệ.Đăng nhập lại.
402Không đủ credit.Nạp thêm credit hoặc nhờ admin cấp.
403Route 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.
404Job 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.
503Má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.

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