샌드박스 API

샌드박스 API를 사용하면 코드나 AI 에이전트가 필요할 때 격리된 클라우드 Linux 머신을 사용할 수 있습니다. 샌드박스를 만들고, 셸 명령을 실행하고, 파일을 읽고 쓴 다음, 중지하거나 삭제할 수 있습니다. 이 모든 작업은 이미지, 동영상, 오디오 생성에 사용하는 것과 동일한 x-api-key와 크레딧 잔액으로 REST를 통해 수행됩니다.

Sandbox(테스트) 키와는 다릅니다. is_test: true로 만든 API 키는 "샌드박스 키"라고 하며 생성 엔드포인트에서 모의 결과를 반환합니다(API 레퍼런스 참고). 여기에서 설명하는 샌드박스 API는 실제 클라우드 머신을 만듭니다. 테스트 키로 샌드박스 API 엔드포인트를 호출할 수 있지만, 모의 결과만 반환하고 머신은 만들지 않습니다.

크기 및 요금

샌드박스를 만들 때 profile을 전달하세요. 샌드박스가 실행 중인 동안 초 단위로 요금이 계산되어 크레딧에서 차감됩니다.

프로필리소스가격
small2 vCPU, 4 GB RAM시간당 $0.036
default4 vCPU, 8 GB RAM시간당 $0.072
large8 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정수301~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": "..."}} 형식으로 반환됩니다.

상태코드의미
400INVALID_PROFILE알 수 없는 profile
402INSUFFICIENT_CREDITS잔액이 샌드박스를 만들거나 다시 시작하는 데 필요한 최소 $1보다 적음
422INVALID_INPUT필드가 누락되었거나 허용 범위를 벗어남(작업 스타일 엔드포인트)
502SANDBOX_UPSTREAM_ERROR일시적인 백엔드 오류. 다시 시도하세요

사용 사례

  • 코딩 에이전트: 저장소를 복제하고, 패키지를 설치하고, 실제 머신에서 테스트를 실행해 실패를 수정합니다.
  • 코드 실행: 생성되었거나 신뢰할 수 없는 코드를 자체 인프라와 분리된 환경에서 실행합니다.
  • 미디어 파이프라인: Muapi 이미지, 동영상, 오디오 모델의 출력에 ffmpeg 또는 사용자 지정 스크립트를 실행합니다.
  • 오픈 소스 앱 호스팅: 사용자의 Muapi 키로 클라우드에서 앱을 실행합니다.

개요는 샌드박스 API 랜딩 페이지를 참고하세요.