🤖 Coco MCP – Hướng Dẫn Dùng Coco Studio qua AI Agent

1. Giới thiệu tổng quan (Overview)

Coco MCP cho phép AI agent (Claude Code, Cursor, Claude trên web…) dùng trực tiếp Coco Partner API bằng ngôn ngữ tự nhiên: bạn chỉ cần nhắn "Tạo video 5 giây 720p từ ảnh này", agent sẽ tự chọn model, báo giá, tạo tác vụ, chờ kết quả và gửi link. Không cần viết code tích hợp, không cần webhook.

🔑 Dùng chính API Key Partner (tạo trong mục API Key trên web Coco Studio): quyền, số dư CC và lịch sử tác vụ giống hệt khi gọi API trực tiếp. Tác vụ tạo qua agent cũng hiện trên web Coco Studio.

🔌 MCP (Model Context Protocol) là chuẩn mở để AI agent gọi công cụ bên ngoài.

2. Kết nối

Môi trường	Địa chỉ MCP
Production	`https://mcp.cocostudio.io/mcp`

API Key được gửi qua header apikey. Nên đặt key vào biến môi trường thay vì dán thẳng vào file cấu hình hay khung chat:

1. Claude Code

Mở Claude Code, gõ /mcp để kiểm tra coco đã kết nối.

2. Cursor

Thêm vào ~/.cursor/mcp.json (mọi dự án) hoặc .cursor/mcp.json (một dự án):

{
  "mcpServers": {
    "coco": {
      "url": "https://mcp.cocostudio.io/mcp",
      "headers": { "apikey": "${env:COCO_API_KEY}" }
    }
  }
}

3. Claude trên web (claude.ai)

Settings → Connectors → Add custom connector.

Name: Coco, URL: https://mcp.cocostudio.io/mcp.

Thêm header apikey với giá trị là API Key, rồi lưu.

Trong khung chat, bật connector Coco và hỏi như bình thường.

⚠️ Lưu ý: Claude trên web chạy lệnh trong sandbox của Anthropic, không phải trên máy bạn. Với gói Free/Pro/Max, sandbox chỉ truy cập được một số domain cố định, nên không upload được file lên Coco qua agent (lỗi Could not resolve host). Gói Team/Enterprise: owner có thể thêm domain lưu trữ của Coco vào allowlist tại Organization settings → Capabilities. Cần dùng file trên máy làm tham chiếu thì nên dùng Claude Code hoặc Cursor.

3. Cách một tác vụ chạy

Tạo ảnh, video, audio là tác vụ bất đồng bộ. Agent sẽ đi theo thứ tự:

list_models → get_model_schema: chọn model và xem model nhận tham số gì (độ phân giải, tỉ lệ, số giây, số ảnh tham chiếu…). Agent dùng giá trị dạng chữ ("720p", "16:9", "reference"), không cần nhớ mã số enum của Partner API.

estimate_cost: báo giá miễn phí, đúng bằng số CC sẽ bị tạm giữ khi tạo.

create_image / create_video / create_audio / upscale_video: gửi một lần, nhận taskId (ví dụ video:54ea3264-…).

wait_for_task: mỗi lần chờ tối đa ~50 giây; chưa xong thì trả done: false (không phải lỗi), agent gọi tiếp.

Xong: outputs chứa URL file và assetId. assetId dùng tiếp được cho bước sau (ảnh → video → upscale) mà không cần tải về.

4. Danh sách tool

Nhóm	Tool	Mô tả	Phí
Khám phá	`list_models`, `get_model_schema`	Danh sách model và tham số từng model hỗ trợ	Miễn phí
	`estimate_cost`	Báo giá ảnh, video, audio, upscale, asset kèm số dư hiện có	Miễn phí
Tạo	`create_image`	Tạo ảnh, có thể kèm ảnh tham chiếu	Tốn CC
	`create_video`, `finalize_video_draft`	Tạo video (reference / first & last frame, draft 480p); nâng draft lên 1080p	Tốn CC
	`create_audio`	TTS, clone giọng; Seed Audio 1.5: lồng tiếng video, tách lời/nhạc nền	Tốn CC
	`upscale_video`	Upscale video Coco hoặc video từ URL https	Tốn CC
Theo dõi	`get_task`, `wait_for_task`, `list_tasks`	Trạng thái, kết quả, danh sách tác vụ	Miễn phí
File & asset	`create_upload`, `complete_upload`	Đưa file từ máy lên Coco, nhận `assetId` (thư mục API Uploads trong Asset library)	Miễn phí
	`register_asset`, `list_assets`, `get_asset`	Asset Advanced Creation (ảnh/video có người thật)	2 CC / 15 ngày
Glossary	`list_glossaries`, `save_glossary`	Thuật ngữ dịch cố định cho lồng tiếng	Miễn phí
Xoá	`delete_failed_task`, `delete_asset`, `delete_glossary`	Xoá vĩnh viễn, client sẽ hỏi xác nhận	—

5. Làm việc với file

Upload file từ máy: agent gọi create_upload, chạy lệnh curl mà tool trả về để gửi file thẳng lên kho lưu trữ (file không đi qua máy chủ MCP), rồi gọi complete_upload để nhận assetId. Client sẽ hỏi bạn có cho chạy lệnh đó không.

Giới hạn: ảnh PNG/JPEG/WebP/GIF ≤ 30MB; video MP4/MOV/WebM ≤ 200MB; audio MP3/WAV/OGG/M4A/FLAC ≤ 15MB. Upload miễn phí, tính vào dung lượng lưu trữ như upload trên web.

Sửa một vùng trên ảnh: khoanh vùng cần sửa lên ảnh bằng công cụ vẽ bất kỳ, đưa ảnh đã khoanh cho agent và nói rõ nét khoanh trong câu lệnh, ví dụ "Xoá cái ly trong vòng tròn đỏ, rồi bỏ luôn vòng tròn". Giống chế độ Draw trên web.

Tải kết quả: URL trong outputs tải trực tiếp được (agent có thể chạy curl -o).

6. Chi phí & an toàn

Báo giá trước khi tạo: estimate_cost dùng đúng công thức tính giá của lệnh tạo. Upscale video từ URL ngoài chỉ là giá ước tính (cần biết trước thời lượng).

Không bị trừ tiền hai lần: mỗi lệnh tạo kèm header Idempotency-Key; lệnh gửi lại do mạng chập chờn trả về đúng tác vụ đã tạo. Gặp lỗi SUBMIT_UNCERTAIN thì gọi lại đúng tool với idempotencyKey trong lỗi, không tạo lại từ đầu.

Giữ tiền rồi mới trừ: CC được tạm giữ khi bắt đầu, chỉ bị trừ khi có kết quả; thất bại được hoàn toàn bộ.

Không có lệnh huỷ: tác vụ đã gửi sẽ chạy đến khi xong.

Giới hạn tần suất (theo company, mỗi phút): tạo video / upscale 10, ảnh / audio 15, Advanced Creation 10, báo giá 60, upload 30.

7. Câu lệnh mẫu

Câu lệnh	Agent sẽ làm
Coco có những model video nào? Seedance 2.5 hỗ trợ độ phân giải nào?	Chỉ đọc, miễn phí
Video 8 giây 720p tỉ lệ 9:16 bằng Seedance 2.0 hết bao nhiêu CC?	`estimate_cost`, chưa tạo gì
Tạo 1 ảnh 2K 1:1: chai nước hoa thủy tinh trên nền đá cẩm thạch, ánh sáng studio.	Báo giá → tạo → chờ → gửi link
Lấy ảnh vừa tạo làm khung hình đầu, tạo video 5 giây 720p 16:9.	Video mode First & Last frame với `assetId` của ảnh
Ghép ./coffee.png và ./banhmi.png thành ảnh combo, rồi làm video 5 giây dùng cả 3 ảnh làm tham chiếu.	Upload 2 file → ảnh 2 tham chiếu → video 3 tham chiếu
Upscale video đó lên 1080p 30fps rồi gửi link.	`upscale_video` với `videoTaskId`
Mình đồng ý chi tối đa 30 CC, trong ngân sách cứ tự làm.	Agent tự chạy các bước mà không hỏi lại, vượt thì dừng

8. Bảng mã lỗi thường gặp (Error Codes)

Mã	Ý nghĩa	Cách xử lý
`AUTH_INVALID`	API Key sai, đã xoá hoặc chưa gửi header `apikey`	Kiểm tra biến `COCO_API_KEY` và cấu hình client
`INVALID_INPUT`	Tham số sai / model không hỗ trợ (thông báo nêu giá trị hợp lệ)	Agent tự sửa lại. Không bị trừ tiền
`INSUFFICIENT_BALANCE`	Số dư không đủ	Nạp thêm CC
`RATE_LIMITED`	Vượt giới hạn tần suất	Chờ theo thời gian trong thông báo
`ASSET_NOT_READY`	Asset Advanced Creation chưa được duyệt	Chờ asset ready
`KYC_REQUIRED`, `ADVANCED_CREATION_NOT_ACTIVATED`	Chưa đủ điều kiện Advanced Creation	Bật Advanced Creation và KYC trên web
`SUBMIT_UNCERTAIN`	Không chắc lệnh tạo đã tới Coco	Gọi lại với `idempotencyKey` trong lỗi
`UPSTREAM_UNAVAILABLE`, `NETWORK`	Sự cố hệ thống hoặc mạng	Thử lại sau ít phút

9. Bảo mật API Key

🔒 Ai có API Key là tiêu được CC của bạn. Không dán key vào khung chat, không commit vào git. Coco MCP không ghi key vào log. Nghi lộ key thì xoá key trong mục API Key trên web, key mất hiệu lực ngay. Các thao tác tốn tiền hoặc xoá đều được đánh dấu để client hỏi bạn trước khi chạy — không nên bật chế độ tự động chấp nhận mọi tool.

🤖 Coco MCP – Hướng Dẫn Dùng Coco Studio qua AI Agent

1. Giới thiệu tổng quan (Overview)#

2. Kết nối#

1. Claude Code#

2. Cursor#

3. Claude trên web (claude.ai)#

3. Cách một tác vụ chạy#

4. Danh sách tool#

5. Làm việc với file#

6. Chi phí & an toàn#

7. Câu lệnh mẫu#

8. Bảng mã lỗi thường gặp (Error Codes)#

9. Bảo mật API Key#