Compeller

ทางการ

สร้างมิวสิควิดีโอ AI และภาพที่ตอบสนองต่อเสียงเพลงผ่าน MCP

เอกสาร

ปลายทาง MCP ของ Compeller (`/api/mcp`)

ปลายทาง MCP ของ Compeller ใช้ Model Context Protocol ในรูปแบบ JSON-RPC 2.0 แบบบางที่ครอบทับ REST API v1 เดิม มีไว้สำหรับผู้รวมระบบเอเจนต์ (Claude Desktop, Cursor, ไคลเอนต์ MCP แบบกำหนดเอง, DigiRAMP) ที่สื่อสารด้วย MCP โดยตรงแทนที่จะเป็น HTTP ดิบ

การขนส่ง: Streamable HTTP (ข้อความ JSON-RPC เดียวต่อ HTTP POST หนึ่งครั้ง)
URL: POST https://compeller.ai/api/mcp
เวอร์ชันโปรโตคอล: 2024-11-05
ชื่อเซิร์ฟเวอร์ / เวอร์ชัน: compeller-mcp / ดูผลลัพธ์ initialize
สัญญาเครื่องมือ: รายการเครื่องมือด้านล่างคือสัญญาการรวมระบบสาธารณะ ใช้ tools/list สำหรับชุดที่โฆษณาตอนรันไทม์บนเซิร์ฟเวอร์ที่ปรับใช้
รายการไดเรกทอรี: Official MCP Registry · Smithery · Glama

การตรวจสอบสิทธิ์

เมธอดไม่ระบุตัวตน (การค้นพบ): initialize, tools/list, ping, notifications/initialized รวมถึงเครื่องมือไม่ระบุตัวตน get_capabilities, get_pricing, list_styles

เครื่องมืออื่นๆ ทุกตัวต้องใช้โทเค็น API ของ Compeller ที่ส่งผ่านคำขอ HTTP เอง ไม่ใช่ภายในเนื้อหา JSON-RPC ส่วนหัวใดก็ได้ที่ใช้ได้:

Authorization: Bearer <api-token>
X-API-Token: <api-token>

โทเค็นออกให้ต่อ User ของ Compeller (โทเค็นเดียวกับที่ใช้โดย /api/v1/*) เอเจนต์สามารถรับได้สองวิธี:

ขอให้ผู้ใช้เข้าสู่ระบบ เปิด บัญชี → การเข้าถึง API แสดงโทเค็น และวางลงในที่เก็บความลับของเอเจนต์
ใช้ปลายทางเข้าสู่ระบบที่มีอยู่และส่ง access_token เป็นโทเค็น bearer ไม่จำเป็นต้องมีหรือคาดหวังส่วนหัว Cookie:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","password":"..."}'

ผู้ใช้ปกติจะได้รับ username และ access_token roles จะปรากฏเฉพาะบัญชีที่มีบทบาทเกินกว่า ROLE_COMPELLER พื้นฐาน; refresh_token และ expires_in จะปรากฏเฉพาะเมื่อไม่ว่างเปล่า

หรือแลกเปลี่ยนข้อมูลประจำตัวผ่านตัวช่วย auth v1 ซึ่งจะส่งคืนโทเค็น API ถาวร:

curl -s -X POST https://compeller.ai/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"..."}'

โทเค็นที่ขาดหายหรือไม่ถูกต้องจะปรากฏเป็น ข้อผิดพลาดของเครื่องมือ (isError: true) พร้อมข้อความ "API token required." / "Invalid API token." ไม่ใช่เป็นข้อผิดพลาด JSON-RPC เพื่อให้ไคลเอนต์ MCP สามารถแจ้งให้ผู้ใช้ป้อนข้อมูลประจำตัวได้

เมธอด JSON-RPC

เมธอด	วัตถุประสงค์	ผลลัพธ์ HTTP
`initialize`	การจับมือความสามารถ ส่งคืน `protocolVersion`, `serverInfo`, `capabilities`	200 ผลลัพธ์ JSON-RPC
`notifications/initialized`	การตอบรับจากไคลเอนต์ ไม่มีเนื้อหาตอบกลับ	204
`tools/list`	แสดงรายการเครื่องมือทั้งหมดพร้อม schema + คำอธิบาย	200 ผลลัพธ์ JSON-RPC
`tools/call`	เรียกใช้เครื่องมือ `params = {name, arguments}`	200 ผลลัพธ์ JSON-RPC (ข้อผิดพลาดของเครื่องมือกลับมาเป็น `{isError: true, content: [...]}`)
`ping`	การรักษาการเชื่อมต่อแบบไม่ทำอะไร	200 JSON-RPC `result: {}`

เมธอดที่ไม่รู้จักจะส่งคืนข้อผิดพลาด JSON-RPC -32601 Method not found ชื่อเครื่องมือที่ไม่รู้จักจะส่งคืน -32602 Unknown tool เนื้อหา JSON ที่มีรูปแบบผิดพลาดจะส่งคืน -32700 Parse error jsonrpc ที่ขาดหาย/ผิด หรือ method ที่ขาดหายจะส่งคืน -32600 Invalid Request

เครื่องมือ

เครื่องมือทั้งหมดส่งคืนรายการ content เดี่ยวของ type: text ซึ่งฟิลด์ text เป็นเอาต์พุตที่มีโครงสร้างในรูปแบบ JSON เมื่อล้มเหลว รูปร่างการตอบกลับเดียวกันจะถูกส่งคืนพร้อม isError: true และข้อความแสดงข้อผิดพลาดที่มนุษย์อ่านได้ใน content[0].text — ไม่เคยเป็น error ของ JSON-RPC

การค้นพบ (ไม่ต้องตรวจสอบสิทธิ์)

เครื่องมือ	อินพุต	ส่งคืน
`get_capabilities`	—	`productName`, `version`, `capabilities[]`, `spec_url`, `enums` (`styles`, `target_platforms`, `aspect_ratios`), `auth`, `media_limits`, `rate_limits`
`get_pricing`	—	`plans[]` พร้อม `id`, `name`, `monthlyUsd`, `features[]`
`list_styles`	—	`styles[]` พร้อม `id`, `name` (`id` คือค่าที่แน่นอนที่ `create_compel` / `create_compel_from_music` ยอมรับสำหรับ `style`)

สื่อและเพลง (ต้องตรวจสอบสิทธิ์ยกเว้นที่ระบุไว้)

เครื่องมือ	จำเป็น	ไม่บังคับ	ส่งคืน
`search_music`	`query`	`limit`	ผลลัพธ์การค้นหาเพลงสาธารณะที่เหมาะสำหรับ `create_compel_from_music` ไม่ต้องตรวจสอบสิทธิ์
`upload_media`	—	`name`, `mime_type`, `type`	คำแนะนำการอัปโหลดที่ชี้ไปยัง `POST /api/v1/media`
`search_media`	—	`type` (`audio`/`image`/`video`/`text`), `limit` (≤100, ค่าเริ่มต้น 20), `offset`	`media[]`, `paging`

Compels (ต้องตรวจสอบสิทธิ์)

เครื่องมือ	จำเป็น	ไม่บังคับ	ส่งคืน
`create_compel_from_music`	`track_id`	`title`, `style`, `target_platform`, `aspect_ratio`, `artist_context`	`compel_id`, `status`, `next_action`
`create_compel`	`title`, `primary_media_id`	`style`, `target_platform`, `aspect_ratio`, `artist_context`	`compel_id`, `status: QUEUED`
`get_compel`	`compel_id`	—	`compel_id`, `title`, `status`, `progress_percent`, `stage`, `rendering_id`, `created_at`, `human_url`, `next_action`
`start_render`	`compel_id`	—	เริ่มการเรนเดอร์ขั้นสุดท้ายเมื่อ compel พร้อม; ส่งคืนสถานะและการดำเนินการถัดไป
`cancel_compel`	`compel_id`	—	ยกเลิก compel ที่กำลังดำเนินการ (idempotent — ที่ยกเลิกแล้วสำเร็จ); ส่งคืน `compel_id`, `status: CANCELLED`, `stage`
`list_compels`	—	`limit` (≤100), `offset`	`compels[]`, `paging`
`search_compels`	`query`	`limit`	`compels[]`, `count`

style, target_platform และ aspect_ratio ถูกจำกัดโดย enum ใน schema ของเครื่องมือ (ดู get_capabilities.enums); ค่า style มาจาก list_styles โดยตรง

บัญชี (ต้องตรวจสอบสิทธิ์)

เครื่องมือ	อินพุต	ส่งคืน
`get_account_credits`	—	`plan`, `minutes_remaining`, `free_minutes_remaining`, `paid_minutes_remaining`, `minutes_total`, `quota_exceeded`, `api_eligible`, `billing_url` — เรียกก่อนการเรนเดอร์ที่มีค่าใช้จ่ายสูงเพื่อตัดสินใจโดยคำนึงถึงต้นทุน

การเรนเดอร์ (ต้องตรวจสอบสิทธิ์)

เครื่องมือ	จำเป็น	ส่งคืน
`list_renderings`	`compel_id`	`compel_id`, `renderings[]` พร้อม `rendering_id`, `status`, `download_url`
`get_rendering`	`rendering_id`	`rendering_id`, `compel_id`, `status`, `download_url`

download_url ชี้ไปที่ GET /api/v1/renderings/{id}/download (รองรับ HTTP Range) การตอบกลับ compel/การเรนเดอร์ที่เสร็จสมบูรณ์ยังรวมถึงการส่งต่อ react พร้อมการดาวน์โหลด REACT ฟรี (https://compeller.ai/download/desktop) และ URL เรียนรู้เพิ่มเติม (https://compeller.ai/react) เพื่อให้เอเจนต์สามารถบอกผู้ใช้ถึงวิธีสัมผัส compel ในฐานะระบบการแสดงสด

Webhooks (ต้องตรวจสอบสิทธิ์)

เอเจนต์ที่รวมระบบกับ Compeller สามารถลงทะเบียนด้วยตนเองเพื่อรับการแจ้งเตือนแบบพุชที่ลงนามสำหรับเหตุการณ์วงจรชีวิตของ compel แทนการโพล get_compel สมัครรับ compel.ready เพื่อทราบช่วงเวลาที่ compel พร้อมเรนเดอร์ (จากนั้นเรียก start_render) โดยไม่ต้องโพล; compel.completed / compel.failed เป็นเหตุการณ์สิ้นสุด

เครื่องมือ	จำเป็น	ไม่บังคับ	ส่งคืน
`register_webhook`	`url` (HTTPS, ≤2048 ตัวอักษร)	`events[]` — ค่าเริ่มต้นเป็น `[""]`; ค่าที่รู้จัก: ``, `compel.ready`, `compel.completed`, `compel.failed`	`webhook_id`, `url`, `events`, `secret` (ส่งคืนเพียงครั้งเดียว), `active`, `created_at`
`list_webhooks`	—	—	`webhooks[]` — `webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at` ความลับจะ ไม่ ถูกส่งคืนโดยเครื่องมือนี้
`update_webhook`	`webhook_id`	`url`, `events[]`, `active` — อย่างน้อยหนึ่งรายการ	`webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at` ความลับจะ ไม่ ถูกส่งคืน; ใช้ `rotate_webhook_secret` สำหรับสิ่งนั้น
`delete_webhook`	`webhook_id`	—	`webhook_id`, `deleted: true`
`test_webhook_delivery`	`webhook_id`	—	`webhook_id`, `event_id`, `event_type: "webhook.test"`, `delivered`, `response_status?`, `response_body_preview?`, `latency_ms`, `error?` แบบซิงโครนัส — เครื่องมือรอให้ปลายทางของผู้รวมระบบตอบกลับ (สูงสุด 5 วินาที) ความลับจะ ไม่ ถูกส่งคืน
`rotate_webhook_secret`	`webhook_id`	—	`webhook_id`, `url`, `events`, `active`, `secret` (ใหม่ — ส่งคืนเพียงครั้งเดียว), `created_at`, `updated_at` ความลับเก่าถูกทำให้ใช้ไม่ได้ทันที

ชื่อเหตุการณ์ที่ไม่รู้จักจะยุบรวมเป็นไวลด์การ์ด * อย่างเงียบๆ; สิ่งนี้สะท้อน POST /api/v1/webhooks เพื่อให้เอเจนต์ไม่สร้างการสมัครที่ไม่ทำอะไรเลย

การจัดส่งเป็นแบบอย่างน้อยหนึ่งครั้ง แต่ละเหตุการณ์จะถูกพยายามทันที และหากปลายทางของคุณไม่สามารถเข้าถึงได้หรือส่งคืนค่าที่ไม่ใช่ 2xx จะลองใหม่พร้อมการถอยกลับ — รวมสูงสุด 6 ครั้ง (ทันที จากนั้นหลังจาก 1 นาที, 5 นาที, 30 นาที, 2 ชั่วโมง, 6 ชั่วโมง) ทุกความพยายามมี X-Compeller-Event-Id เดียวกันและเนื้อหาที่ลงนามเหมือนกันทุกประการ ดังนั้นให้ลบรายการซ้ำตาม id นั้น หากความพยายามทั้งหมดหมดลง เหตุการณ์จะถูกทิ้ง; กระทบยอดผ่าน get_compel

register_webhook ปฏิเสธปลายทางที่ชี้ไปยังโครงสร้างพื้นฐานภายในด้วยข้อผิดพลาดของเครื่องมือ: loopback, ช่วงส่วนตัว RFC1918, link-local (รวมถึง IP ข้อมูลเมตาคลาวด์เช่น 169.254.169.254), IPv6 ULA, CGNAT, multicast, ที่อยู่ที่ไม่ระบุ และชื่อโฮสต์ที่ลงท้ายด้วย .local / .internal / .localhost การตรวจสอบเดียวกันนี้จะทำงานอีกครั้ง ณ เวลาจัดส่งกับ DNS ที่แก้ไขแล้วในทุกความพยายาม ดังนั้นชื่อโฮสต์ที่ผูกใหม่กับ IP ที่ถูกบล็อกหลังจากการลงทะเบียนจะถูกข้ามสำหรับความพยายามนั้น (บันทึก); หากยังคงถูกบล็อก มันก็จะใช้งบประมาณการลองใหม่จนหมดแล้วถูกทิ้ง

test_webhook_delivery ส่งเหตุการณ์ webhook.test สังเคราะห์พร้อมลายเซ็น HMAC-SHA256 และรอการตอบกลับจากปลายทางแบบซิงโครนัส มันละเว้น events ที่สมัครไว้ของปลายทาง (จัดส่งเสมอ) และใช้การตรวจสอบความปลอดภัย URL เช่นเดียวกับการจัดส่งจริง การตอบกลับที่ไม่ใช่ 2xx จะปรากฏเป็น delivered: false แต่การเรียก MCP เองยังคงส่งคืนสำเร็จ — ผลลัพธ์คือเพย์โหลด

update_webhook ยอมรับ url, events, active ใดๆ (อย่างน้อยหนึ่งรายการ) การตรวจสอบ URL สะท้อน register_webhook ความลับจะไม่ถูกส่งคืนโดยเครื่องมือนี้

rotate_webhook_secret สร้างความลับการลงนาม hex 64 ตัวอักษรใหม่ ส่งคืนเพียงครั้งเดียว และทำให้ความลับก่อนหน้าใช้ไม่ได้ทันที เก็บความลับใหม่เมื่อได้รับก่อนการจัดส่งจริงครั้งถัดไป

การจัดส่งทุกครั้งลงนามเหมือนกับเส้นทาง REST — ดูส่วน Webhooks ของ openapi.yaml สำหรับสัญญาซองจดหมายและส่วนหัวแบบเต็ม

เซสชันตัวอย่าง

# 1. Handshake
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2. List tools
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Register a webhook (auth required)
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api-token>' \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"tools/call",
        "params":{
          "name":"register_webhook",
          "arguments":{
            "url":"https://hooks.my-agent.io/compeller",
            "events":["compel.completed","compel.failed"]
          }
        }
      }'

การตอบกลับขั้นตอนที่ 3 คือ JSON-RPC result ที่มี content[0].text — ซึ่งเป็นเอกสาร JSON ที่มี webhook_id, secret ฯลฯ เก็บ secret ทันที; เซิร์ฟเวอร์จะไม่ส่งคืนอีก

รหัสข้อผิดพลาด

รหัส	ความหมาย	สาเหตุ
`-32700`	ข้อผิดพลาดการแยกวิเคราะห์	เนื้อหาไม่ใช่ JSON ที่ถูกต้อง
`-32600`	คำขอไม่ถูกต้อง	`jsonrpc` ขาดหาย/ผิด, `method` ขาดหาย, เนื้อหาว่างเปล่า
`-32601`	ไม่พบเมธอด	เมธอด JSON-RPC ที่ไม่รู้จัก
`-32602`	พารามิเตอร์ไม่ถูกต้อง	เครื่องมือที่ไม่รู้จัก, `name` ของเครื่องมือขาดหาย, รูปร่าง `params` ไม่ดี
`-32603`	ข้อผิดพลาดภายใน	ข้อยกเว้นที่ไม่ได้จัดการ (บันทึกฝั่งเซิร์ฟเวอร์)

ความล้มเหลวระดับเครื่องมือ (การตรวจสอบความถูกต้อง, การตรวจสอบสิทธิ์, ไม่พบ) จะถูกส่งคืนภายในการตอบกลับ JSON-RPC ที่สำเร็จเป็น {result: {isError: true, content: [{type: "text", text: "..."}]}} นี่เป็นไปตามแบบแผน MCP — มันให้ LLM เห็นและแสดงความล้มเหลวตามคำต่อคำ แผนผังการตัดสินใจด้านเสียงของเอเจนต์: หากผู้ใช้ให้ไฟล์ MP3/WAV/FLAC ให้ใช้ upload_media จากนั้น create_compel; หากผู้ใช้ให้เพียงสตริงชื่อเพลง/ศิลปิน ให้ใช้ search_music จากนั้น create_compel_from_music; อย่าสังเคราะห์เสียงเว้นแต่จะมีการร้องขอให้สร้างเสียงทดสอบอย่างชัดเจน