호출 한 번으로 완성된 미디어까지
run은 생성을 요청하고, API가 권장하는 백오프로 폴링한 뒤, result.url이 포함된 완료된 요청을 반환해요.
한눈에 보기
Mage는 API용 오픈소스 SDK를 제공해요. TypeScript와 JavaScript용 npm의 @mage-space/sdk, Python용 PyPI의 mage-space, ComfyUI용 comfyui-mage 노드 팩이 있어요. 모두 REST API를 감싸서 28개 모델 전체의 타입 설정, 자동 폴링, 멱등 재시도, 업로드를 지원해요.
3
SDK 및 연동
28
타입 지원 모델
MIT
오픈소스
$0
설치하기
나에게 맞는 것 고르기
npm install @mage-space/sdk
모든 Mage 모델의 타입 설정으로 Node.js에서 이미지, 영상, 오디오를 생성하세요. 호출 한 번으로 요청하고, 기다리고, 결과를 받아요.
pip install mage-space
동기 및 asyncio 클라이언트와 모든 Mage 모델의 타입 설정으로 Python에서 이미지, 영상, 오디오를 생성하세요.
comfy node install comfyui-mage
Mango, Cherry, Seed Audio를 비롯한 모든 Mage 모델을 ComfyUI 노드로 사용하세요. GPU도, 모델 다운로드도 필요 없습니다.
빠른 시작
패키지를 설치하고 MAGE_API_KEY를 내보낸 다음 모델을 실행하세요.
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.run('mango', {
prompt: 'Editorial portrait in soft daylight, 35mm film look',
aspect_ratio: '4:5',
model_id: 'mango-v3',
});
console.log(request.result.url);# pip install mage-space
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
request = mage.run("mango", {
"prompt": "Editorial portrait in soft daylight, 35mm film look",
"aspect_ratio": "4:5",
"model_id": "mango-v3",
})
print(request["result"]["url"])기본 제공
run은 생성을 요청하고, API가 권장하는 백오프로 폴링한 뒤, result.url이 포함된 완료된 요청을 반환해요.
모든 요청에는 멱등성 키가 포함돼요. 네트워크 오류와 서버 오류는 백오프를 적용해 재시도하며, 재시도된 요청은 다시 청구되지 않아요.
데이터 URL로 보내기에 너무 큰 파일은 서명된 업로드를 거치며, 티켓 발급, PUT, 크기 확인을 대신 처리해 줘요.
API 거부 응답에는 HTTP 상태, 오류 코드, 요청 ID가 포함돼요. 실패하거나 취소된 생성과 시간 초과에는 각각 별도의 오류 유형이 있어요.
패키지
| SDK | 패키지 | 설치 | 소스 |
|---|---|---|---|
| TypeScript SDK | @mage-space/sdk | npm install @mage-space/sdk | GitHub |
| Python SDK | mage-space | pip install mage-space | GitHub |
| ComfyUI용 Mage | comfyui-mage | comfy node install comfyui-mage | GitHub |
FAQ
네. SDK와 ComfyUI 노드는 GitHub에서 MIT 라이선스로 공개되어 있으며, 설치는 무료예요. 실행한 생성에 대해서만 각 모델의 표시 가격만큼 Gems로 결제하면 돼요.
네. 새 모델의 id를 문자열로 전달하면 실행돼요. SDK는 모든 모델이 공통으로 쓰는 필드를 기준으로 설정을 확인해요. API 레퍼런스가 바뀔 때마다 봇이 타입을 업데이트하므로, 새 모델은 다음 릴리스에서 전용 타입과 함께 제공돼요.
모든 요청에는 Idempotency-Key가 포함돼요. SDK는 호출마다 새 키를 만들고, 해당 호출을 직접 재시도할 때는 같은 키를 다시 사용해요. 그래서 재시도한 요청은 원래 요청을 그대로 반환하며 추가로 결제되지 않아요.
현재 0.x 베타 버전이라 마이너 버전에서 변경될 수 있어요. API 자체는 별도로 버전을 관리하며 v1 안에서는 안정적으로 유지돼요.
구독료나 월 요금은 없습니다. 생성할 때마다 해당 모델의 표시 가격만큼 Gems로 결제하며, 기본 팩 기준 1,000 Gems는 $1입니다. 각 모델 페이지에서 기본 설정 기준 가격을 확인할 수 있고, 응답에는 실제 청구 금액이 표시됩니다. 생성에 실패하면 환불되지만, Mage 콘텐츠 정책에 따라 차단된 경우는 환불되지 않습니다. 잔액이 부족한 요청은 결제 전에 거부됩니다.
아니요. API는 Gems만으로 사용할 수 있습니다. 멤버십 플랜과 앱 내 무제한 생성은 API 요청에 적용되지 않으므로, Gems가 있는 Mage 계정이라면 누구나 호출할 수 있습니다.
네. API와 MCP 서버를 통해 만든 콘텐츠를 포함해, Mage로 만든 콘텐츠는 상업적으로 사용할 수 있어요. 출처 표기는 감사하지만 필수는 아니에요.
계정 하나, Gems 잔액 하나로 모든 모델을 사용하세요. 생성한 만큼만 결제하면 됩니다.