API Sandbox
Sandbox API cung cấp cho mã hoặc tác nhân AI của bạn một máy Linux đám mây biệt lập theo yêu cầu. Tạo sandbox, chạy lệnh shell, đọc và ghi tệp, sau đó dừng hoặc xóa sandbox — tất cả qua REST với cùng x-api-key và số dư tín dụng bạn dùng để tạo ảnh, video và âm thanh.
Không giống khóa Sandbox (test). Khóa API được tạo với
is_test: trueđược gọi là “khóa sandbox” và trả về kết quả giả lập cho các endpoint tạo nội dung (xem Tài liệu tham khảo API). Sandbox API được mô tả ở đây tạo các máy đám mây thực. Khóa test có thể gọi các endpoint của Sandbox API, nhưng sẽ trả về kết quả giả lập và không tạo gì cả.
Cấu hình và giá
Truyền profile khi tạo sandbox. Tính phí theo giây trong khi sandbox đang chạy, trừ vào số dư tín dụng của bạn.
| Cấu hình | Tài nguyên | Giá |
|---|---|---|
small | 2 vCPU, 4 GB RAM | $0.036 / giờ |
default | 4 vCPU, 8 GB RAM | $0.072 / giờ |
large | 8 vCPU, 16 GB RAM | $0.144 / giờ |
- Mức giá theo giờ được cố định khi sandbox được tạo.
- Sandbox đã dừng không mất phí. Tệp được giữ lại khi sandbox dừng.
- Bạn cần có số dư ít nhất $1 để tạo hoặc tiếp tục chạy sandbox.
Bắt đầu nhanh
export MUAPI_KEY="your-api-key"
# 1. Tạo sandbox
curl -X POST https://api.muapi.ai/api/v1/sandboxes \
-H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
-d '{"profile": "default"}'
# -> {"id": "…", "state": "running", "profile": "default", "vcpu": 4, "memory_gb": 8, "price_per_hour": 0.072, …}
export ID="<id from the response>"
# 2. Chạy lệnh
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/commands \
-H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
-d '{"command": "python3 --version", "timeout_seconds": 30}'
# 3. Ghi và đọc tệp
curl -X PUT https://api.muapi.ai/api/v1/sandboxes/$ID/files \
-H "x-api-key: $MUAPI_KEY" -H "Content-Type: application/json" \
-d '{"path": "/home/user/hello.py", "content": "print(\"hi\")"}'
curl "https://api.muapi.ai/api/v1/sandboxes/$ID/files?path=/home/user/hello.py" \
-H "x-api-key: $MUAPI_KEY"
# 4. Dừng sandbox (tạm ngừng tính phí)
curl -X POST https://api.muapi.ai/api/v1/sandboxes/$ID/stop \
-H "x-api-key: $MUAPI_KEY"
Python
import os, requests
BASE = "https://api.muapi.ai/api/v1/sandboxes"
H = {"x-api-key": os.environ["MUAPI_KEY"]}
sb = requests.post(BASE, headers=H, json={"profile": "small"}).json()
sid = sb["id"]
out = requests.post(f"{BASE}/{sid}/commands", headers=H,
json={"command": "echo hello && uname -a"}).json()
print(out)
requests.post(f"{BASE}/{sid}/stop", headers=H)
Các endpoint
| Phương thức | Đường dẫn | Mô tả |
|---|---|---|
POST | /api/v1/sandboxes | Tạo sandbox. Nội dung: {"profile": "small" | "default" | "large"} |
GET | /api/v1/sandboxes | Liệt kê các sandbox của bạn |
GET | /api/v1/sandboxes/{id} | Lấy thông tin một sandbox |
POST | /api/v1/sandboxes/{id}/commands | Chạy lệnh shell |
GET | /api/v1/sandboxes/{id}/commands/{process_id} | Trạng thái và đầu ra của lệnh chạy tách nền |
PUT | /api/v1/sandboxes/{id}/files | Ghi tệp |
GET | /api/v1/sandboxes/{id}/files?path= | Đọc tệp |
POST | /api/v1/sandboxes/{id}/stop | Dừng sandbox (tạm ngừng tính phí) |
POST | /api/v1/sandboxes/{id}/resume | Tiếp tục chạy sandbox đã dừng |
DELETE | /api/v1/sandboxes/{id} | Xóa sandbox và các tệp của sandbox |
Chạy lệnh
POST /api/v1/sandboxes/{id}/commands
| Trường | Kiểu | Mặc định | Ghi chú |
|---|---|---|---|
command | string | bắt buộc | Lệnh shell, tối đa 20,000 ký tự |
timeout_seconds | integer | 30 | Từ 1 đến 600 |
detached | boolean | false | Chạy ở chế độ nền; kiểm tra trạng thái bằng process_id được trả về |
cwd | string | . | Thư mục làm việc. Thư mục này phải tồn tại từ trước (ví dụ: chạy mkdir -p /home/user/workspace trước) |
Với các tác vụ kéo dài, đặt detached: true, sau đó kiểm tra GET /api/v1/sandboxes/{id}/commands/{process_id}.
Tệp
PUT /files nhận {"path": "...", "content": "..."} với nội dung văn bản thuần (tối đa 2,000,000 ký tự). GET /files?path=... trả về {"path": "...", "content": "..."}.
Vòng đời và tính phí
- Sandbox mới chuyển sang trạng thái
runningtrong vài giây và được cài sẵn Python 3. - Lệnh dừng không hoàn tất ngay lập tức. Việc tính phí dừng tại thời điểm bạn gửi yêu cầu, nhưng nếu tiếp tục chạy ngay thì có thể nhận lỗi xung đột trong vài giây. Lệnh dừng chờ sandbox hoàn tất việc lưu trữ trước khi trả về, vì vậy bạn có thể dừng rồi tiếp tục chạy an toàn.
- Tệp được giữ nguyên khi dừng và tiếp tục chạy sandbox.
- Sandbox sẽ tự động dừng khi số dư không đủ chi trả mức sử dụng hoặc sau 15 phút không hoạt động.
- Sandbox đã dừng sẽ bị xóa sau 14 ngày. Hãy tải xuống mọi thứ bạn cần trước thời hạn đó.
- Mỗi tài khoản có thể có tối đa 3 sandbox cùng lúc.
- Lệnh và thao tác với tệp được thực hiện dưới quyền người dùng thông thường bên trong một máy biệt lập. Bạn chịu trách nhiệm về những gì mình chạy trong máy đó.
Playground và các endpoint dạng tác vụ
Mọi thao tác đều có trong Playground và dưới dạng endpoint kiểu tác vụ, POST /api/v1/sandbox-<operation>, trong đó <operation> là một trong các giá trị create, get, run-command, command-status, write-file, read-file, stop, resume, delete. Các endpoint này nhận những trường tương tự các tuyến REST cùng với sandbox_id khi cần, rồi trả về request_id. Bạn có thể đọc kết quả bằng GET /api/v1/predictions/{request_id}/result, như với mọi mô hình Muapi khác. Chỉ tính phí theo thời gian chạy; bản thân các yêu cầu này không mất phí.
Lỗi
Lỗi có định dạng {"error": {"code": "...", "message": "..."}}.
| Trạng thái | Mã | Ý nghĩa |
|---|---|---|
| 400 | INVALID_PROFILE | profile không xác định |
| 402 | INSUFFICIENT_CREDITS | Số dư thấp hơn mức tối thiểu $1 để tạo hoặc tiếp tục chạy sandbox |
| 422 | INVALID_INPUT | Thiếu trường hoặc giá trị nằm ngoài phạm vi cho phép (các endpoint dạng tác vụ) |
| 502 | SANDBOX_UPSTREAM_ERROR | Lỗi tạm thời ở hệ thống phía sau; hãy thử lại |
Trường hợp sử dụng
- Tác nhân lập trình: sao chép một kho mã, cài đặt gói, chạy kiểm thử và sửa lỗi trên máy thực.
- Thực thi mã: chạy mã được tạo hoặc mã không đáng tin cậy bên ngoài cơ sở hạ tầng của bạn.
- Quy trình xử lý phương tiện: chạy ffmpeg hoặc tập lệnh tùy chỉnh trên đầu ra từ các mô hình tạo ảnh, video và âm thanh của Muapi.
- Ứng dụng mã nguồn mở được lưu trữ: chạy ứng dụng trên đám mây bằng khóa Muapi của chính người dùng.
Xem trang giới thiệu Sandbox API để biết tổng quan.