호출 한 번으로 완성된 미디어까지
run은 생성을 요청하고, API가 권장하는 백오프로 폴링한 뒤, result.url이 포함된 완료된 요청을 반환해요.
한눈에 보기
Mage Python SDK는 Mage API의 공식 오픈 소스 클라이언트이며 mage-space라는 이름으로 배포됩니다. "pip install mage-space"로 설치하고 MAGE_API_KEY를 설정한 뒤, 모델 ID와 설정값으로 mage.run을 호출하면 28개 모델 중 원하는 모델로 완성된 이미지, 영상, 오디오를 받을 수 있어요. Python 3.10 이상에서 실행되며, 모든 생성에는 Gems가 사용됩니다.
3.10+
Python
httpx
HTTP 클라이언트
28
타입 지원 모델
MIT
오픈소스
설정
Python SDK 설치하고 모델 실행하기
패키지 설치
프로젝트에 mage-space를 추가하세요.
pip install mage-spaceAPI 키 설정
mage.space의 API → API Keys에서 키를 만들고 내보내세요. 클라이언트는 MAGE_API_KEY를 읽어요.
export MAGE_API_KEY="mage_sk_..."생성
모델 id와 설정값으로 run을 호출하세요. 결과가 나올 때까지 기다렸다가 반환하며, 출력물은 result.url에 있어요.
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"])
예제
Python SDK 활용하기
모든 예제는 MAGE_API_KEY를 읽는 클라이언트에서 시작해요.
지금 요청하고 나중에 기다리기
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
submitted = mage.generate("cherry", {
"prompt": "Waves rolling onto a black sand beach at sunset",
"resolution": "720p",
"duration": "5",
})
final = mage.requests.wait(
submitted["request_id"],
timeout=900,
on_update=lambda request: print(request["status"]),
)파일 업로드
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
clip = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
mage.run("cherry", {
"prompt": "Restyle this clip as a watercolor painting",
"videos": [clip["url"]],
})저장한 캐릭터 사용하기
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
mage.characters.create(
name="Ana",
handle="ana",
image="https://example.com/ana.png",
)
mage.run("mango", {"prompt": "@ana walking through a night market"})오류 처리
from mage_space import Mage, MageAPIError, MageGenerationError
mage = Mage() # reads MAGE_API_KEY
try:
mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
if error.code == "insufficient_gems":
print("Gems needed:", error.body["error"]["gems_required"])
else:
raise
except MageGenerationError as error:
print("No output:", error.code)SDK를 쓰는 이유
SDK가 대신 처리해 주는 것들
두 번 결제되지 않는 재시도
모든 요청에는 멱등성 키가 포함돼요. 네트워크 오류와 서버 오류는 백오프를 적용해 재시도하며, 재시도된 요청은 다시 청구되지 않아요.
호출 한 번으로 업로드
데이터 URL로 보내기에 너무 큰 파일은 서명된 업로드를 거치며, 티켓 발급, PUT, 크기 확인을 대신 처리해 줘요.
알기 쉬운 오류
API 거부 응답에는 HTTP 상태, 오류 코드, 요청 ID가 포함돼요. 실패하거나 취소된 생성과 시간 초과에는 각각 별도의 오류 유형이 있어요.
동기 및 asyncio
Mage와 AsyncMage는 모든 메서드를 똑같이 제공해요. 비동기 클라이언트는 웹 서버, 노트북, 여러 생성 작업을 동시에 실행하는 파이프라인에 잘 맞습니다.
타입 설정
모델마다 API 레퍼런스에서 생성된 MangoConfig 같은 TypedDict가 있어요. 설정에 이 타입을 지정하면 타입 검사기가 필드를 확인해 줍니다.
레퍼런스
Python SDK 한눈에 보기
모든 모델에 같은 메서드를 쓰며, 모델은 첫 번째 인자로 전달해요.
| 메서드 | 기능 |
|---|---|
| mage.run(model, config) | 생성을 요청하고, 완료될 때까지 기다린 뒤 완료된 요청을 반환해요. |
| mage.generate(model, config) | 생성을 요청하고 요청 정보를 즉시 반환해요. |
| mage.requests.get / cancel / wait | id로 요청을 조회하거나, 중지하거나, 완료될 때까지 기다려요. |
| mage.uploads.upload(data) | 경로, 바이트 또는 최대 100MB 파일을 업로드하고 해당 URL을 반환합니다. |
| mage.characters / mage.references | 저장된 캐릭터와 레퍼런스를 조회, 생성, 삭제해요. |
| mage.account.get() | 내 Gems 잔액이에요. |
| mage.architectures.list() | 옵션과 가격이 포함된 실시간 모델 카탈로그예요. |
모델
이 모델로 시작해 보세요
FAQ
자주 묻는 질문
Python SDK는 asyncio를 지원하나요?
네. AsyncMage는 Mage와 같은 메서드를 await 방식으로 제공하며, 비동기 컨텍스트 매니저로도 사용할 수 있어요.
SDK는 어떤 Python 버전을 지원하나요?
Python 3.10 이상을 지원합니다. 의존성은 httpx와 typing-extensions뿐이에요.
노트북이나 데이터 파이프라인에서도 Python SDK를 쓸 수 있나요?
네. 스크립트와 노트북에서는 Mage를, 여러 생성 작업을 동시에 실행하려면 asyncio와 함께 AsyncMage를 사용하세요. 계정당 최대 20개의 생성 작업을 동시에 진행할 수 있어요.
Mage SDK는 무료인가요? 오픈소스인가요?
네. SDK와 ComfyUI 노드는 GitHub에서 MIT 라이선스로 공개되어 있으며, 설치는 무료예요. 실행한 생성에 대해서만 각 모델의 표시 가격만큼 Gems로 결제하면 돼요.
새로운 Mage 모델도 이전 버전 SDK에서 작동하나요?
네. 새 모델의 id를 문자열로 전달하면 실행돼요. SDK는 모든 모델이 공통으로 쓰는 필드를 기준으로 설정을 확인해요. API 레퍼런스가 바뀔 때마다 봇이 타입을 업데이트하므로, 새 모델은 다음 릴리스에서 전용 타입과 함께 제공돼요.
SDK는 재시도한 요청에 대해 이중 결제를 어떻게 막나요?
모든 요청에는 Idempotency-Key가 포함돼요. SDK는 호출마다 새 키를 만들고, 해당 호출을 직접 재시도할 때는 같은 키를 다시 사용해요. 그래서 재시도한 요청은 원래 요청을 그대로 반환하며 추가로 결제되지 않아요.
SDK는 안정적인가요?
현재 0.x 베타 버전이라 마이너 버전에서 변경될 수 있어요. API 자체는 별도로 버전을 관리하며 v1 안에서는 안정적으로 유지돼요.
Mage API 요금은 얼마인가요?
구독료나 월 요금은 없습니다. 생성할 때마다 해당 모델의 표시 가격만큼 Gems로 결제하며, 기본 팩 기준 1,000 Gems는 $1입니다. 각 모델 페이지에서 기본 설정 기준 가격을 확인할 수 있고, 응답에는 실제 청구 금액이 표시됩니다. 생성에 실패하면 환불되지만, Mage 콘텐츠 정책에 따라 차단된 경우는 환불되지 않습니다. 잔액이 부족한 요청은 결제 전에 거부됩니다.
API를 사용하려면 Mage 멤버십이 필요한가요?
아니요. API는 Gems만으로 사용할 수 있습니다. 멤버십 플랜과 앱 내 무제한 생성은 API 요청에 적용되지 않으므로, Gems가 있는 Mage 계정이라면 누구나 호출할 수 있습니다.
API로 만든 결과물을 상업적으로 사용할 수 있나요?
네. API와 MCP 서버를 통해 만든 콘텐츠를 포함해, Mage로 만든 콘텐츠는 상업적으로 사용할 수 있어요. 출처 표기는 감사하지만 필수는 아니에요.
Mage로 지금 시작하세요
계정 하나, Gems 잔액 하나로 모든 모델을 사용하세요. 생성한 만큼만 결제하면 됩니다.