호출 한 번으로 완성된 미디어까지
run은 생성을 요청하고, API가 권장하는 백오프로 폴링한 뒤, result.url이 포함된 완료된 요청을 반환해요.
한눈에 보기
Mage TypeScript SDK는 Mage API의 공식 오픈 소스 클라이언트로, @mage-space/sdk라는 이름으로 배포돼요. "npm install @mage-space/sdk"로 설치하고 MAGE_API_KEY를 설정한 뒤, 모델 id와 설정값으로 mage.run을 호출하면 28개 모델 중 원하는 모델로 완성된 이미지, 영상, 오디오를 받을 수 있어요. Node.js 20.19 이상 또는 fetch를 지원하는 서버 런타임에서 실행되며, 모든 생성은 Gems로 결제돼요.
20.19+
Node.js
0
런타임 의존성
28
타입 지원 모델
MIT
오픈소스
설정
TypeScript SDK를 설치하고 모델 실행하기
패키지 설치
프로젝트에 @mage-space/sdk를 추가하세요.
npm install @mage-space/sdkAPI 키 설정
mage.space의 API → API Keys에서 키를 만들고 내보내세요. 클라이언트는 MAGE_API_KEY를 읽어요.
export MAGE_API_KEY="mage_sk_..."생성
모델 id와 설정값으로 run을 호출하세요. 결과가 나올 때까지 기다렸다가 반환하며, 출력물은 result.url에 있어요.
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);
예제
TypeScript SDK 활용 예제
모든 예제는 MAGE_API_KEY를 읽는 클라이언트에서 시작해요.
지금 요청하고 나중에 기다리기
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const submitted = await mage.generate('cherry', {
prompt: 'Waves rolling onto a black sand beach at sunset',
resolution: '720p',
duration: '5',
});
const final = await mage.requests.wait(submitted.request_id, {
timeout: 15 * 60_000,
onUpdate: (request) => console.log(request.status),
});파일 업로드
import { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const clip = await mage.uploads.upload(await readFile('clip.mp4'), {
contentType: 'video/mp4',
});
await mage.run('cherry', {
prompt: 'Restyle this clip as a watercolor painting',
videos: [clip.url],
});저장한 캐릭터 사용하기
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
await mage.characters.create({
name: 'Ana',
handle: 'ana',
image: 'https://example.com/ana.png',
});
await mage.run('mango', { prompt: '@ana walking through a night market' });오류 처리
import Mage, { MageAPIError, MageGenerationError } from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
try {
await mage.run('mango', { prompt: 'A lighthouse at night' });
} catch (error) {
if (error instanceof MageAPIError && error.code === 'insufficient_gems') {
// Top up Gems, then try again.
} else if (error instanceof MageGenerationError) {
console.log('No output:', error.code);
} else {
throw error;
}
}SDK를 쓰는 이유
SDK가 대신 처리해 주는 것들
두 번 결제되지 않는 재시도
모든 요청에는 멱등성 키가 포함돼요. 네트워크 오류와 서버 오류는 백오프를 적용해 재시도하며, 재시도된 요청은 다시 청구되지 않아요.
호출 한 번으로 업로드
데이터 URL로 보내기에 너무 큰 파일은 서명된 업로드를 거치며, 티켓 발급, PUT, 크기 확인을 대신 처리해 줘요.
알기 쉬운 오류
API 거부 응답에는 HTTP 상태, 오류 코드, 요청 ID가 포함돼요. 실패하거나 취소된 생성과 시간 초과에는 각각 별도의 오류 유형이 있어요.
모든 모델에 타입 제공
MangoConfig, CherryConfig 등은 API 레퍼런스에서 자동 생성돼요. 에디터가 필드를 자동 완성하고 잘못된 옵션도 잡아 줘요.
의존성 없음
런타임 의존성 없는 ESM이에요. Node.js 내장 fetch를 사용하며, 모든 호출에서 AbortSignal을 쓸 수 있어요.
레퍼런스
TypeScript SDK 한눈에 보기
모든 모델에 같은 메서드를 쓰며, 모델은 첫 번째 인자로 전달해요.
| 메서드 | 기능 |
|---|---|
| mage.run(model, config) | 생성을 요청하고, 완료될 때까지 기다린 뒤 완료된 요청을 반환해요. |
| mage.generate(model, config) | 생성을 요청하고 요청 정보를 즉시 반환해요. |
| mage.requests.get / cancel / wait | id로 요청을 조회하거나, 중지하거나, 완료될 때까지 기다려요. |
| mage.uploads.upload(data) | 최대 100 MB 파일을 업로드하고 URL을 반환해요. |
| mage.characters / mage.references | 저장된 캐릭터와 레퍼런스를 조회, 생성, 삭제해요. |
| mage.account.get() | 내 Gems 잔액이에요. |
| mage.architectures.list() | 옵션과 가격이 포함된 실시간 모델 카탈로그예요. |
모델
이 모델로 시작해 보세요
FAQ
자주 묻는 질문
브라우저에서 Mage TypeScript SDK를 사용할 수 있나요?
아니요. API 키는 내 Gems를 사용하므로 서버에서만 보관하세요. API는 CORS 헤더를 보내지 않아 브라우저에서 직접 호출할 수 없어요. 대신 자체 백엔드를 호출하고, 백엔드에서 SDK를 사용하세요.
TypeScript SDK는 CommonJS에서도 작동하나요?
이 패키지는 ESM 전용이에요. Node.js 20.19 이상에서는 CommonJS에서도 require()로 불러올 수 있어요.
TypeScript SDK는 Next.js에서 작동하나요?
네, 라우트 핸들러나 서버 액션 같은 서버 코드에서 사용할 수 있어요. SDK는 fetch와 AbortSignal 같은 표준 Web API를 기반으로 만들어져, fetch를 지원하는 다른 서버 런타임에서도 작동할 거예요. 다만 CI에서는 Node.js로만 테스트해요.
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 잔액 하나로 모든 모델을 사용하세요. 생성한 만큼만 결제하면 됩니다.