Đến nội dung chính
[ Dành cho lập trình viên ]

Đưa VimeoClip vào code, agent và workflow của bạn

Gửi một link video qua REST API hoặc MCP, nhận clip dọc qua webhook, rồi nối tiếp bằng n8n. Mọi lệnh gọi dùng tài khoản và credit của bạn.

Bốn lối vào cùng một pipeline

Cả bốn đều chạy qua các route của backend, nên quyền, credit và quyền sở hữu job giống hệt dashboard.

REST API

POST /api/process nhận link hoặc file. GET /api/status/{job_id} trả tiến độ và danh sách clip.

Xem API

MCP

POST /mcp cho agent 8 tool: tạo job, tải file lên, đọc trạng thái, liệt kê clip, phụ đề, cắt lại, đăng bài.

Xem MCP

Webhook

Truyền webhook_url để nhận một POST khi job kết thúc. Thêm webhook_secret để body được ký HMAC-SHA256.

Xem webhook

n8n

Hai workflow mẫu đi kèm mã nguồn trong examples/n8n: một bản gửi link rồi nhận clip, một bản chạy theo kênh YouTube.

Xem n8n

Từ link video tới danh sách clip

Ba bước, chạy được với curl và jq. BASE là địa chỉ backend của VimeoClip.

Bash · bash
BASE=http://localhost:8000

# 1. Đăng nhập. Response có access_token.
TOKEN=$(curl -s -X POST "$BASE/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"YOUR_PASSWORD"}' | jq -r .access_token)

# 2. Tạo job. Response có job_id.
JOB_ID=$(curl -s -X POST "$BASE/api/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","acknowledged":true}' | jq -r .job_id)

# 3. Đọc trạng thái và danh sách clip.
curl -s "$BASE/api/status/$JOB_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '{status, progress, clips: .result.clips}'

Mỗi lối vào cần quyền gì

Tài khoản mới có quyền member. Route chưa nằm trong danh sách cho member thì chỉ admin gọi được.

Việc cần làmRouteQuyền tối thiểu
Tạo job, tải file lênPOST /api/process, POST /api/uploadsMember
Đọc trạng thái, tải clip của mìnhGET /api/status/{job_id}, GET /videos/{job_id}/…Member, chủ job
Dùng agentPOST /mcpMember
Sửa phụ đề, cắt lại clipPOST /api/subtitle, POST /api/clip/rerenderAdmin
Đăng hoặc lên lịch bàiPOST /api/social/postAdmin

Chưa đăng nhập thì nhận 401. Member gọi route chỉ dành cho admin thì nhận 403.

Bạn cần gì trước khi gọi

  • Một tài khoản VimeoClip. Địa chỉ gọi là host của dashboard bạn đang dùng.
  • Một khóa API dạng osk_ tạo ở trang Truy cập API, hoặc token phiên lấy qua POST /api/auth/login bằng mật khẩu.
  • Đủ credit trong tài khoản, vì mỗi job giữ credit ngay khi được nhận. Tài khoản mới có thể có 0 credit.
  • Máy chủ có GEMINI_API_KEY hoặc LLM_BASE_URL, hoặc request gửi kèm header X-Gemini-Key.
  • Quyền admin nếu bạn dùng MCP, sửa clip hoặc đăng bài.

Câu hỏi thường gặp

Có. POST /api/process giữ credit của tài khoản khi job được nhận, kể cả tài khoản admin. MCP gọi lại đúng route đó nên trừ theo cùng cách. Job lỗi hoặc bị huỷ được hoàn lại.

Bắt đầu bằng một request

Trang API có đủ field của POST /api/process, cách đọc clip và các mã lỗi.

Video minh hoạ (stock), không phải kết quả của VimeoClip · Storyblocks