Sandbox API

Sandbox API เปิดให้โค้ดหรือเอเจนต์ AI ใช้งานเครื่อง Linux บนคลาวด์แบบแยกส่วนได้เมื่อต้องการ คุณสามารถสร้างแซนด์บ็อกซ์ รันคำสั่งเชลล์ อ่านและเขียนไฟล์ แล้วหยุดหรือลบแซนด์บ็อกซ์ได้ ทั้งหมดผ่าน REST โดยใช้ x-api-key และยอดเครดิตเดียวกับที่ใช้สร้างภาพ วิดีโอ และเสียง

ไม่ใช่คีย์ Sandbox (ทดสอบ) แบบเดียวกัน API key ที่สร้างด้วย is_test: true เรียกว่า "sandbox keys" และจะส่งผลลัพธ์จำลองสำหรับ endpoint การสร้าง (ดูข้อมูลอ้างอิง API) ส่วน Sandbox API ที่อธิบายที่นี่ใช้สร้างเครื่องบนคลาวด์จริง คีย์ทดสอบเรียกใช้ endpoint ของ Sandbox API ได้ แต่จะส่งผลลัพธ์จำลองและไม่สร้างอะไรขึ้นมา

ขนาดและราคา

ส่ง profile เมื่อสร้างแซนด์บ็อกซ์ ระบบคิดค่าบริการเป็นรายวินาทีขณะที่แซนด์บ็อกซ์ทำงาน โดยหักจากเครดิตของคุณ

โปรไฟล์ทรัพยากรราคา
small2 vCPU, RAM 4 GB$0.036 / ชั่วโมง
default4 vCPU, RAM 8 GB$0.072 / ชั่วโมง
large8 vCPU, RAM 16 GB$0.144 / ชั่วโมง
  • อัตราค่าบริการรายชั่วโมงจะถูกกำหนดไว้ตอนสร้างแซนด์บ็อกซ์
  • แซนด์บ็อกซ์ที่หยุดอยู่ไม่มีค่าใช้จ่าย ไฟล์จะถูกเก็บไว้ขณะที่หยุดทำงาน
  • คุณต้องมียอดเงินอย่างน้อย $1 เพื่อสร้างหรือกลับมาใช้งานแซนด์บ็อกซ์อีกครั้ง

เริ่มต้นอย่างรวดเร็ว

export MUAPI_KEY="your-api-key"

# 1. สร้างแซนด์บ็อกซ์
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. รันคำสั่ง
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. เขียนและอ่านไฟล์
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. หยุดแซนด์บ็อกซ์ (หยุดคิดค่าบริการ)
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)

Endpoints

วิธีเส้นทางคำอธิบาย
POST/api/v1/sandboxesสร้างแซนด์บ็อกซ์ เนื้อหาคำขอ: {"profile": "small" | "default" | "large"}
GET/api/v1/sandboxesแสดงรายการแซนด์บ็อกซ์ของคุณ
GET/api/v1/sandboxes/{id}ดูข้อมูลแซนด์บ็อกซ์หนึ่งรายการ
POST/api/v1/sandboxes/{id}/commandsรันคำสั่งเชลล์
GET/api/v1/sandboxes/{id}/commands/{process_id}ดูสถานะและผลลัพธ์ของคำสั่งที่ทำงานแยกอยู่เบื้องหลัง
PUT/api/v1/sandboxes/{id}/filesเขียนไฟล์
GET/api/v1/sandboxes/{id}/files?path=อ่านไฟล์
POST/api/v1/sandboxes/{id}/stopหยุดแซนด์บ็อกซ์ (หยุดคิดค่าบริการ)
POST/api/v1/sandboxes/{id}/resumeกลับมาใช้งานแซนด์บ็อกซ์ที่หยุดอยู่
DELETE/api/v1/sandboxes/{id}ลบแซนด์บ็อกซ์และไฟล์

รันคำสั่ง

POST /api/v1/sandboxes/{id}/commands

ฟิลด์ชนิดค่าเริ่มต้นหมายเหตุ
commandstringจำเป็นคำสั่งเชลล์ ความยาวสูงสุด 20,000 อักขระ
timeout_secondsinteger30ตั้งแต่ 1 ถึง 600
detachedbooleanfalseรันในเบื้องหลัง แล้วตรวจสอบสถานะด้วย process_id ที่ส่งกลับมา
cwdstring.ไดเรกทอรีทำงาน ต้องมีอยู่แล้ว (ตัวอย่างเช่น รัน mkdir -p /home/user/workspace ก่อน)

สำหรับงานที่ใช้เวลานาน ให้ตั้ง detached: true แล้วตรวจสอบสถานะด้วย GET /api/v1/sandboxes/{id}/commands/{process_id}

ไฟล์

PUT /files รับ {"path": "...", "content": "..."} โดย content เป็นข้อความธรรมดา (ความยาวสูงสุด 2,000,000 อักขระ) ส่วน GET /files?path=... จะส่งกลับ {"path": "...", "content": "..."}

วงจรการใช้งานและการคิดค่าบริการ

  • แซนด์บ็อกซ์ใหม่จะอยู่ในสถานะ running ภายในไม่กี่วินาที และติดตั้ง Python 3 ไว้ล่วงหน้า
  • การหยุดไม่เกิดขึ้นทันที ระบบหยุดคิดค่าบริการตั้งแต่เวลาที่คุณส่งคำขอ แต่การกลับมาใช้งานทันทีอาจได้รับข้อขัดแย้งเป็นเวลาสองสามวินาที คำสั่งหยุดจะรอให้แซนด์บ็อกซ์จัดเก็บข้อมูลเสร็จก่อนส่งผลกลับมา ดังนั้นการหยุดแล้วกลับมาใช้งานจึงทำได้อย่างปลอดภัย
  • ไฟล์จะยังอยู่หลังจากหยุดและกลับมาใช้งานแซนด์บ็อกซ์
  • ระบบจะหยุดแซนด์บ็อกซ์โดยอัตโนมัติ เมื่อยอดเงินไม่เพียงพอสำหรับการใช้งาน หรือเมื่อไม่มีการใช้งานเป็นเวลา 15 นาที
  • ระบบจะลบแซนด์บ็อกซ์ที่หยุดอยู่หลังจาก 14 วัน ดาวน์โหลดไฟล์ที่ต้องการก่อนถึงเวลานั้น
  • แต่ละบัญชีมีแซนด์บ็อกซ์พร้อมกันได้สูงสุด 3 รายการ
  • คำสั่งและการเข้าถึงไฟล์ทำงานในสิทธิ์ผู้ใช้ทั่วไปภายในเครื่องที่แยกส่วน คุณเป็นผู้รับผิดชอบต่อสิ่งที่รันในเครื่องนั้น

Playground และ endpoint รูปแบบงาน

ทุกการดำเนินการมีให้ใช้ใน Playground และผ่าน endpoint รูปแบบงาน POST /api/v1/sandbox-<operation> โดย <operation> เป็นหนึ่งใน create, get, run-command, command-status, write-file, read-file, stop, resume, delete endpoint เหล่านี้รับฟิลด์เดียวกับเส้นทาง REST พร้อม sandbox_id ในกรณีที่เกี่ยวข้อง และส่งกลับ request_id ซึ่งคุณสามารถใช้เรียก GET /api/v1/predictions/{request_id}/result ได้เหมือนกับโมเดล Muapi อื่น ๆ ระบบคิดค่าประมวลผลตามเวลาที่แซนด์บ็อกซ์ทำงานเท่านั้น คำขอเหล่านี้ไม่มีค่าใช้จ่าย

ข้อผิดพลาด

ข้อผิดพลาดใช้รูปแบบ {"error": {"code": "...", "message": "..."}}

สถานะรหัสความหมาย
400INVALID_PROFILEไม่รู้จัก profile
402INSUFFICIENT_CREDITSยอดเงินต่ำกว่าขั้นต่ำ $1 สำหรับสร้างหรือกลับมาใช้งาน
422INVALID_INPUTฟิลด์ขาดหายหรืออยู่นอกช่วงที่กำหนด (endpoint รูปแบบงาน)
502SANDBOX_UPSTREAM_ERRORข้อผิดพลาดชั่วคราวจากระบบแบ็กเอนด์ ให้ลองอีกครั้ง

กรณีการใช้งาน

  • เอเจนต์เขียนโค้ด: โคลน repo ติดตั้งแพ็กเกจ รันการทดสอบ และแก้ข้อผิดพลาดบนเครื่องจริง
  • การรันโค้ด: รันโค้ดที่สร้างขึ้นหรือไม่น่าเชื่อถือ โดยแยกออกจากโครงสร้างพื้นฐานของคุณ
  • ไปป์ไลน์สื่อ: รัน ffmpeg หรือสคริปต์ที่กำหนดเองกับผลลัพธ์จากโมเดลสร้างภาพ วิดีโอ และเสียงของ Muapi
  • แอปโอเพนซอร์สที่โฮสต์ไว้: รันแอปบนคลาวด์ด้วย Muapi key ของผู้ใช้เอง

ดูภาพรวมได้ที่หน้าแนะนำ Sandbox API