샌드박스 API
샌드박스 API를 사용하면 코드나 AI 에이전트가 필요할 때 격리된 클라우드 Linux 머신을 사용할 수 있습니다. 샌드박스를 만들고, 셸 명령을 실행하고, 파일을 읽고 쓴 다음, 중지하거나 삭제할 수 있습니다. 이 모든 작업은 이미지, 동영상, 오디오 생성에 사용하는 것과 동일한 x-api-key와 크레딧 잔액으로 REST를 통해 수행됩니다.
Sandbox(테스트) 키와는 다릅니다.
is_test: true로 만든 API 키는 "샌드박스 키"라고 하며 생성 엔드포인트에서 모의 결과를 반환합니다(API 레퍼런스 참고). 여기에서 설명하는 샌드박스 API는 실제 클라우드 머신을 만듭니다. 테스트 키로 샌드박스 API 엔드포인트를 호출할 수 있지만, 모의 결과만 반환하고 머신은 만들지 않습니다.
크기 및 요금
샌드박스를 만들 때 profile을 전달하세요. 샌드박스가 실행 중인 동안 초 단위로 요금이 계산되어 크레딧에서 차감됩니다.
| 프로필 | 리소스 | 가격 |
|---|---|---|
small | 2 vCPU, 4 GB RAM | 시간당 $0.036 |
default | 4 vCPU, 8 GB RAM | 시간당 $0.072 |
large | 8 vCPU, 16 GB RAM | 시간당 $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)
엔드포인트
| 메서드 | 경로 | 설명 |
|---|---|---|
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
| 필드 | 유형 | 기본값 | 참고 |
|---|---|---|---|
command | 문자열 | 필수 | 셸 명령. 최대 20,000자 |
timeout_seconds | 정수 | 30 | 1~600 |
detached | 불리언 | false | 백그라운드에서 실행. 반환된 process_id로 상태를 조회하세요 |
cwd | 문자열 | . | 작업 디렉터리. 이미 존재해야 합니다(예: 먼저 mkdir -p /home/user/workspace 실행) |
오래 걸리는 작업에는 detached: true를 설정한 다음 GET /api/v1/sandboxes/{id}/commands/{process_id}를 호출해 상태를 조회하세요.
파일
PUT /files에는 일반 텍스트 콘텐츠를 포함한 {"path": "...", "content": "..."}를 전달합니다(최대 2,000,000자). GET /files?path=...는 {"path": "...", "content": "..."}를 반환합니다.
수명 주기 및 요금
- 새 샌드박스는 몇 초 내에
running상태가 되며 Python 3이 사전 설치되어 있습니다. - 중지는 즉시 완료되지 않습니다. 중지를 요청한 시점부터 요금 청구가 멈추지만, 바로 다시 시작하면 몇 초 동안 충돌 오류가 반환될 수 있습니다. 중지 요청은 샌드박스의 보관 작업이 끝날 때까지 기다렸다가 반환되므로 중지 후 다시 시작해도 안전합니다.
- 파일은 중지와 재시작 후에도 유지됩니다.
- 잔액으로 사용 요금을 충당할 수 없거나 15분 동안 활동이 없으면 샌드박스가 자동으로 중지됩니다.
- 중지된 샌드박스는 14일 후 삭제됩니다. 필요한 파일은 그 전에 다운로드하세요.
- 계정당 동시에 최대 3개의 샌드박스를 사용할 수 있습니다.
- 명령 실행과 파일 접근은 격리된 머신 안에서 일반 사용자 권한으로 수행됩니다. 머신에서 실행하는 작업에 대한 책임은 사용자에게 있습니다.
플레이그라운드 및 작업 스타일 엔드포인트
모든 작업은 플레이그라운드와 작업 스타일 엔드포인트인 POST /api/v1/sandbox-<operation>에서도 사용할 수 있습니다. <operation>에는 create, get, run-command, command-status, write-file, read-file, stop, resume, delete 중 하나를 지정합니다. 이 엔드포인트에는 REST 경로와 동일한 필드와 필요한 경우 sandbox_id를 전달하며, 다른 Muapi 모델과 마찬가지로 GET /api/v1/predictions/{request_id}/result에서 조회할 수 있는 request_id를 반환합니다. 컴퓨팅 요금은 실행 시간에 대해서만 부과되며, 요청 자체는 무료입니다.
오류
오류는 {"error": {"code": "...", "message": "..."}} 형식으로 반환됩니다.
| 상태 | 코드 | 의미 |
|---|---|---|
| 400 | INVALID_PROFILE | 알 수 없는 profile |
| 402 | INSUFFICIENT_CREDITS | 잔액이 샌드박스를 만들거나 다시 시작하는 데 필요한 최소 $1보다 적음 |
| 422 | INVALID_INPUT | 필드가 누락되었거나 허용 범위를 벗어남(작업 스타일 엔드포인트) |
| 502 | SANDBOX_UPSTREAM_ERROR | 일시적인 백엔드 오류. 다시 시도하세요 |
사용 사례
- 코딩 에이전트: 저장소를 복제하고, 패키지를 설치하고, 실제 머신에서 테스트를 실행해 실패를 수정합니다.
- 코드 실행: 생성되었거나 신뢰할 수 없는 코드를 자체 인프라와 분리된 환경에서 실행합니다.
- 미디어 파이프라인: Muapi 이미지, 동영상, 오디오 모델의 출력에 ffmpeg 또는 사용자 지정 스크립트를 실행합니다.
- 오픈 소스 앱 호스팅: 사용자의 Muapi 키로 클라우드에서 앱을 실행합니다.
개요는 샌드박스 API 랜딩 페이지를 참고하세요.