Để agent cắt clip thay bạn qua MCP
Backend có sẵn endpoint MCP tại POST /mcp trên chính host của bạn. Agent nhận 8 tool để tạo job, đọc trạng thái, liệt kê clip, chỉnh phụ đề và cắt lại.
Bạn cần gì để kết nối
- Một khóa API dạng osk_ (tạo ở trang Truy cập API) hoặc token phiên. Không có thì /mcp trả 401. Mỗi tool chạy với quyền của tài khoản, nên tool chỉ dành cho admin trả lỗi với member.
- Token gửi trong header Authorization: Bearer. Cookie đăng nhập không dùng được, vì các tool chỉ chuyển tiếp header Authorization, X-API-Key, X-Gemini-Key và X-Upload-Post-Key.
- Khóa osk_ không hết hạn cho tới khi bị thu hồi. Token phiên chỉ sống 30 ngày; khi hết hạn, đăng nhập lại rồi cập nhật cấu hình của client.
- Đủ credit: process_video gọi POST /api/process nên giữ credit như một job thường.
- Người dùng có quyền xử lý nội dung. process_video từ chối nếu confirm_rights khác true.
Kết nối client
Máy chủ dùng HTTP thuần: POST JSON-RPC, trả JSON, không có SSE và không có session. Client MCP nào hỗ trợ HTTP và gửi được header đều dùng được. Ví dụ dưới là Claude Code.
# BASE là địa chỉ VimeoClip bạn dùng. TOKEN là token phiên của admin.
BASE=http://localhost:8000
TOKEN=$(curl -s -X POST "$BASE/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"email":"admin@example.com","password":"YOUR_PASSWORD"}' | jq -r .access_token)
claude mcp add --transport http openshorts "$BASE/mcp" \
--header "Authorization: Bearer $TOKEN"curl -s -X POST "$BASE/mcp" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
| jq -r '.result.tools[].name'curl -s -X POST "$BASE/mcp" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "process_video",
"arguments": {
"source_url": "https://www.youtube.com/watch?v=VIDEO_ID",
"confirm_rights": true,
"target_clips": 5
}
}
}' | jq .result.structuredContent8 tool
Mỗi tool gọi lại đúng một route REST của chính ứng dụng, với header của người gọi.
| Tool | Tham số bắt buộc | Tham số khác | Việc nó làm |
|---|---|---|---|
| process_video | confirm_rights, cùng source_url hoặc upload_id | target_clips, clip_min_seconds, clip_max_seconds, output_format, layouts, captions, caption_preset, auto_hook, hook_style, moment_hint, clip_workflow, clip_lenses, source_language, caption_language, test_mode, webhook_url, webhook_secret, force_low_quality và các field xử lý khác | Tạo job từ link hoặc file đã tải lên, trả job_id ngay. |
| create_upload | Không có | filename | Đặt chỗ tải file, trả upload_id và upload_url. |
| get_job_status | job_id | Không có | Trạng thái, 10 dòng log cuối, lỗi nếu có, clip khi đã có. |
| list_clips | job_id | Không có | Clip của job đã xong: tiêu đề, mô tả từng nền tảng, điểm, video_url. |
| get_quota | Không có | Không có | Xem lưu ý bên dưới: tool này chưa trả số dư. |
| add_subtitles | job_id, clip_index | style, position, font_size, font_name, font_color, highlight_color, uppercase | Đổi kiểu phụ đề của một clip. |
| recut_clip | job_id, clip_index, segments | snap_to_words, reapply_captions, framing | Render lại clip từ danh sách đoạn tính theo giây của video nguồn. |
| publish_clip | job_id, clip_index, platforms | title, description, scheduled_date, timezone | Đăng lên tiktok, instagram, youtube. Xem lưu ý bên dưới. |
clip_index bắt đầu từ 0 và lấy từ list_clips.
Luồng gọi điển hình
process_video trả job_id ngay, nên agent không chờ trong một lần gọi.
Gọi process_video
Truyền nguyên link người dùng đưa. Máy chủ tự tải video, agent không cần mở link.
Theo dõi job
Gọi get_job_status mỗi 30 đến 60 giây, hoặc truyền webhook_url để được gọi lại.
Đọc clip
Khi status là completed, gọi list_clips.
Chỉnh tiếp nếu cần
Dùng add_subtitles để đổi phụ đề, recut_clip để cắt lại.
Những điểm cần biết trước
Các tool chạy đúng theo code hiện tại, nên có vài chỗ cần biết trước khi giao cho agent.
- get_quota luôn trả ghi chú không có quota phút, dù job vẫn giữ credit. Muốn xem số dư thật, gọi GET /api/me.
- publish_clip chưa gửi được tên profile Upload-Post, nên route có thể trả 400 "Missing Upload-Post user profile". Hãy gọi thẳng POST /api/social/post với field user_id.
- create_upload tạo upload_url từ PUBLIC_API_URL. Khi máy chủ chưa đặt biến này, upload_url trỏ về địa chỉ nội bộ của tool.
- Lệnh PUT file và các link video_url đều cần token, vì /api/uploads và /videos không mở cho khách.
- list_clips trả video_url tuyệt đối khi có PUBLIC_API_URL. Nếu không có, bạn nhận đường dẫn tương đối.
Tải file lên cho create_upload
Khác với lời nhắc trong mô tả tool, lệnh PUT phải kèm token.
# create_upload trả upload_id và upload_url.
curl -T video.mp4 "UPLOAD_URL" -H "Authorization: Bearer $TOKEN"Câu hỏi thường gặp
POST /mcp trên cùng host với dashboard bạn đang dùng, ví dụ https://<host>/mcp.
Có, khi admin bật quyền Truy cập API cho tài khoản đó; nếu chưa bật, /mcp trả 403. Member kết nối bằng khóa của mình. Các tool gọi route chỉ dành cho admin (phụ đề, cắt lại, đăng bài) vẫn nhận 403 "This feature currently requires an administrator".
Có. process_video gọi POST /api/process, nên credit được giữ giống job tạo từ dashboard.
Máy chủ nhận protocolVersion 2025-06-18, 2025-03-26 và 2024-11-05. Không hỗ trợ gửi nhiều message trong một request.
Cần tự gọi route phía sau?
Trang API liệt kê field của POST /api/process, cách đọc clip và mã lỗi.
Video minh hoạ (stock), không phải kết quả của VimeoClip · Storyblocks




