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