Mage SDK · Python
Mage Python SDK
동기 및 asyncio 클라이언트와 모든 Mage 모델용 타입 설정으로 Python에서 이미지, 영상, 오디오를 생성하세요.
pip install mage-space한눈에 보기
Mage Python SDK는 mage-space로 배포되는 Mage API의 공식 오픈 소스 클라이언트입니다. "pip install mage-space"로 설치하고 MAGE_API_KEY를 설정한 뒤, 모델 ID와 설정값으로 mage.run을 호출하면 37개 모델 중 원하는 모델로 완성된 이미지, 동영상, 오디오를 받을 수 있어요. Python 3.10 이상에서 실행되며, 모든 생성은 Gems로 결제돼요.
- 3.10+Python
- httpxHTTP 클라이언트
- 37타입 지원 모델
- 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-v4", }) 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가 대신 처리해 주는 것들
호출 한 번으로 완성된 미디어까지
run은 생성을 요청하고, API가 권장하는 백오프로 폴링한 뒤, result.url이 포함된 완료된 요청을 반환해요.
두 번 결제되지 않는 재시도
모든 요청에는 멱등성 키가 포함돼요. 네트워크 오류와 서버 오류는 백오프를 적용해 재시도하며, 재시도된 요청은 다시 청구되지 않아요.
호출 한 번으로 업로드
데이터 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() | 옵션과 가격이 포함된 실시간 모델 카탈로그예요. |
모델
이 모델로 시작해 보세요
Guava API
사진처럼 보이는 포토리얼리즘
Mango API
Mage의 대표 이미지 모델 시리즈
Nano Banana 2 API
선명하고 읽기 쉬운 텍스트, 최대 4K
Cherry API
Mage의 대표 영상 모델 시리즈
Lemon API
모든 영상 기능을 더 부담 없는 가격에
Seed Audio API
프롬프트 하나로 음성, 음악, 효과음까지
FAQ
자주 묻는 질문
Python SDK는 asyncio를 지원하나요?
SDK는 어떤 Python 버전을 지원하나요?
노트북이나 데이터 파이프라인에서도 Python SDK를 쓸 수 있나요?
Mage SDK는 무료인가요? 오픈소스인가요?
새로운 Mage 모델도 이전 버전 SDK에서 작동하나요?
SDK는 재시도한 요청에 대해 이중 결제를 어떻게 막나요?
SDK는 안정적인가요?
Mage API 요금은 얼마인가요?
API를 사용하려면 Mage 멤버십이 필요한가요?
API로 만든 결과물을 상업적으로 사용할 수 있나요?
Mage로 지금 시작하세요
계정 하나, Gems 잔액 하나로 모든 모델을 사용하세요. 생성한 만큼만 결제하면 됩니다.