Mage SDK · TypeScript
SDK TypeScript của Mage
Tạo ảnh, video và âm thanh bằng AI từ Node.js với cấu hình có kiểu dữ liệu cho mọi mô hình Mage. Một lệnh gọi sẽ gửi yêu cầu, chờ và trả về kết quả.
npm install @mage-space/sdkXem nhanh
Mage TypeScript SDK là máy khách chính thức, mã nguồn mở của Mage API, được phát hành dưới tên @mage-space/sdk. Cài bằng "npm install @mage-space/sdk", đặt MAGE_API_KEY, rồi gọi mage.run với một model id và một cấu hình để nhận ảnh, video hoặc âm thanh hoàn chỉnh từ bất kỳ mô hình nào trong 37 mô hình. SDK chạy trên Node.js 20.19 trở lên, hoặc bất kỳ môi trường máy chủ nào có fetch, và mỗi lần tạo đều trả bằng Gems.
- 20.19+Node.js
- 0Phụ thuộc lúc chạy
- 37Mô hình có định kiểu
- MITMã nguồn mở
Thiết lập
Cài SDK TypeScript và chạy một mô hình
Cài đặt gói
Thêm @mage-space/sdk vào dự án của bạn.
npm install @mage-space/sdkĐặt khóa API
Tạo khóa tại API → API Keys trên mage.space rồi export khóa đó. Ứng dụng khách sẽ đọc MAGE_API_KEY.
export MAGE_API_KEY="mage_sk_..."Tạo
Gọi run với id mô hình và cấu hình của nó. Lệnh sẽ chờ kết quả rồi trả về; đầu ra nằm ở 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);
Ví dụ
SDK TypeScript trong thực tế
Mỗi ví dụ đều bắt đầu từ một ứng dụng khách đọc MAGE_API_KEY.
Gửi trước, chờ sau
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),
});Tải tệp lên
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],
});Dùng nhân vật đã lưu
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' });Xử lý lỗi
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;
}
}Vì sao nên dùng SDK
Những việc SDK làm giúp bạn
Một lệnh gọi, có ngay kết quả
run gửi yêu cầu tạo, polling theo backoff mà API khuyến nghị và trả về yêu cầu đã hoàn tất cùng result.url.
Thử lại mà không bao giờ bị tính phí hai lần
Mỗi lần gửi đều kèm một idempotency key. Lỗi mạng và lỗi máy chủ được thử lại với backoff, và lần gửi được thử lại sẽ không bị tính phí thêm.
Tải tệp lên chỉ với một lệnh gọi
Các tệp quá lớn cho data URL sẽ đi qua signed upload, còn ticket, PUT và bước kiểm tra kích thước đã có SDK lo.
Lỗi rõ ràng
Khi API từ chối, bạn nhận được HTTP status, mã lỗi và request id; lần tạo thất bại hoặc bị hủy và lỗi hết thời gian chờ đều có loại lỗi riêng.
Có kiểu dữ liệu cho mọi mô hình
MangoConfig, CherryConfig và các kiểu còn lại được tạo từ tài liệu tham khảo API, nên trình soạn thảo sẽ gợi ý các trường và bắt lỗi tùy chọn không hợp lệ.
Không phụ thuộc bên ngoài
ESM, không có phụ thuộc lúc chạy. SDK dùng fetch tích hợp sẵn của Node.js và mọi lệnh gọi đều nhận một AbortSignal.
Tham khảo
SDK TypeScript trong một cái nhìn
Cùng một bộ phương thức dùng cho mọi mô hình; mô hình là đối số đầu tiên.
| Phương thức | Chức năng |
|---|---|
| mage.run(model, config) | Gửi một lượt tạo, chờ hoàn tất và trả về yêu cầu đã hoàn thành. |
| mage.generate(model, config) | Gửi một lượt tạo và trả về yêu cầu ngay lập tức. |
| mage.requests.get / cancel / wait | Xem, dừng hoặc chờ một yêu cầu theo id. |
| mage.uploads.upload(data) | Tải lên tệp tối đa 100 MB và trả về URL của tệp. |
| mage.characters / mage.references | Liệt kê, tạo và xóa các nhân vật và ảnh tham chiếu đã lưu. |
| mage.account.get() | Số dư Gems của bạn. |
| mage.architectures.list() | Danh mục mô hình trực tiếp kèm tùy chọn và giá. |
Mô hình
Bắt đầu với các mô hình này
Guava API
Chân thực đến mức như ảnh chụp thật
Mango API
Dòng mô hình ảnh chủ lực của chúng tôi
Nano Banana 2 API
Chữ sắc nét, dễ đọc, lên đến 4K
Cherry API
Dòng mô hình video chủ lực của chúng tôi
Lemon API
Đủ mọi tính năng video, với mức giá dễ chịu hơn
Seed Audio API
Giọng nói, nhạc và hiệu ứng âm thanh từ một prompt
FAQ
Câu hỏi thường gặp
Tôi có thể dùng SDK TypeScript của Mage trong trình duyệt không?
SDK TypeScript có hoạt động với CommonJS không?
SDK TypeScript có hoạt động với Next.js không?
SDK của Mage có miễn phí và là mã nguồn mở không?
Các mô hình Mage mới có chạy được với SDK cũ hơn không?
SDK tránh trả tiền hai lần cho một yêu cầu được thử lại bằng cách nào?
SDK đã ổn định chưa?
Mage API có giá bao nhiêu?
Tôi có cần gói thành viên Mage để dùng API không?
Tôi có thể dùng kết quả từ API cho mục đích thương mại không?
Bắt đầu xây dựng với Mage
Một tài khoản, một số dư Gems, mọi mô hình. Bạn chỉ trả tiền cho những gì mình tạo.