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ìnhTài nguyênGiá
small2 vCPU, 4 GB RAM$0.036 / giờ
default4 vCPU, 8 GB RAM$0.072 / giờ
large8 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ẫnMô tả
POST/api/v1/sandboxesTạo sandbox. Nội dung: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesLiệ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}/commandsChạ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}/filesGhi tệp
GET/api/v1/sandboxes/{id}/files?path=Đọc tệp
POST/api/v1/sandboxes/{id}/stopDừng sandbox (tạm ngừng tính phí)
POST/api/v1/sandboxes/{id}/resumeTiế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ườngKiểuMặc địnhGhi chú
commandstringbắt buộcLệnh shell, tối đa 20,000 ký tự
timeout_secondsinteger30Từ 1 đến 600
detachedbooleanfalseChạy ở chế độ nền; kiểm tra trạng thái bằng process_id được trả về
cwdstring.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 running trong 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áiMãÝ nghĩa
400INVALID_PROFILEprofile không xác định
402INSUFFICIENT_CREDITSSố dư thấp hơn mức tối thiểu $1 để tạo hoặc tiếp tục chạy sandbox
422INVALID_INPUTThiế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ụ)
502SANDBOX_UPSTREAM_ERRORLỗ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.