Đến nội dung chính
[ MCP server ]

Để 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.

Kết nối · bash
# 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"
Liệt kê tool · bash
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'
Gọi tool · bash
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.structuredContent

8 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.

ToolTham số bắt buộcTham số khácViệc nó làm
process_videoconfirm_rights, cùng source_url hoặc upload_idtarget_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ácTạo job từ link hoặc file đã tải lên, trả job_id ngay.
create_uploadKhông cófilenameĐặt chỗ tải file, trả upload_id và upload_url.
get_job_statusjob_idKhông cóTrạng thái, 10 dòng log cuối, lỗi nếu có, clip khi đã có.
list_clipsjob_idKhông cóClip của job đã xong: tiêu đề, mô tả từng nền tảng, điểm, video_url.
get_quotaKhông cóKhông cóXem lưu ý bên dưới: tool này chưa trả số dư.
add_subtitlesjob_id, clip_indexstyle, position, font_size, font_name, font_color, highlight_color, uppercaseĐổi kiểu phụ đề của một clip.
recut_clipjob_id, clip_index, segmentssnap_to_words, reapply_captions, framingRender lại clip từ danh sách đoạn tính theo giây của video nguồn.
publish_clipjob_id, clip_index, platformstitle, 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.

  1. 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.

  2. 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.

  3. Đọc clip

    Khi status là completed, gọi list_clips.

  4. 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.

PUT · bash
# 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ầ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