Chuyển đến nội dung

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/sdk

Xem 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

  1. Cài đặt gói

    Thêm @mage-space/sdk vào dự án của bạn.

    npm install @mage-space/sdk
  2. Đặ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_..."
  3. 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ứcChứ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 / waitXem, 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.referencesLiệ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

  • Ảnh · từ 37 Gems

    Guava API

    Chân thực đến mức như ảnh chụp thật

  • Hình ảnh · từ 42 Gems

    Mango API

    Dòng mô hình ảnh chủ lực của chúng tôi

  • Hình ảnh · từ 51 Gems

    Nano Banana 2 API

    Chữ sắc nét, dễ đọc, lên đến 4K

  • Video · từ 618 Gems

    Cherry API

    Dòng mô hình video chủ lực của chúng tôi

  • Video · từ 245 Gems

    Lemon API

    Đủ mọi tính năng video, với mức giá dễ chịu hơn

  • Âm thanh · từ 19 Gems

    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?
Không. Khóa API sẽ tiêu tốn Gems của bạn, vì vậy hãy giữ nó trên máy chủ của bạn. API không gửi header CORS, nên trình duyệt không thể gọi trực tiếp; hãy gọi backend của chính bạn và để backend đó dùng SDK.
SDK TypeScript có hoạt động với CommonJS không?
Gói này chỉ hỗ trợ ESM. Từ Node.js 20.19 trở lên, bạn cũng có thể dùng require() để nạp nó từ CommonJS.
SDK TypeScript có hoạt động với Next.js không?
Có, trong mã phía máy chủ như route handler và server action. SDK được xây dựng trên fetch và các Web API chuẩn như AbortSignal, nên các môi trường chạy phía máy chủ khác có fetch cũng nên hoạt động, dù CI chỉ kiểm thử trên Node.js.
SDK của Mage có miễn phí và là mã nguồn mở không?
Có. SDK và các node ComfyUI được cấp phép MIT trên GitHub, và việc cài đặt hoàn toàn miễn phí. Bạn chỉ trả tiền cho những lượt tạo mà bạn chạy, bằng Gems, theo giá niêm yết của từng mô hình.
Các mô hình Mage mới có chạy được với SDK cũ hơn không?
Có. Chỉ cần truyền id của mô hình mới dưới dạng chuỗi là chạy được; SDK sẽ kiểm tra cấu hình dựa trên các trường mà mọi mô hình đều có. Một bot sẽ cập nhật các kiểu dữ liệu mỗi khi tài liệu tham khảo API thay đổi, nên mô hình mới sẽ có kiểu dữ liệu riêng ở bản phát hành kế tiếp.
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?
Mỗi lượt gửi đều kèm một Idempotency-Key. SDK tạo khóa mới cho mỗi lệnh gọi và dùng lại khóa đó khi tự thử lại lệnh gọi ấy, nên lượt gửi được thử lại sẽ trả về yêu cầu ban đầu và không bị tính phí.
SDK đã ổn định chưa?
SDK đang ở giai đoạn beta với phiên bản 0.x, nên phiên bản phụ vẫn có thể thay đổi chúng. Bản thân API được đánh phiên bản riêng và vẫn ổn định trong v1.
Mage API có giá bao nhiêu?
Không có gói đăng ký hay phí hàng tháng. Mỗi lượt tạo được trả bằng Gems theo giá niêm yết của mô hình, và 1.000 Gems có giá 1 $ với gói tiêu chuẩn. Trang của từng mô hình đều ghi giá theo cài đặt mặc định, và mỗi phản hồi đều cho biết chính xác khoản đã tính. Lượt tạo bị lỗi sẽ được hoàn lại; lượt bị chặn bởi chính sách nội dung của Mage thì không. Yêu cầu vượt quá số dư của bạn sẽ bị từ chối trước khi tính bất kỳ khoản phí nào.
Tôi có cần gói thành viên Mage để dùng API không?
Không. API chỉ chạy bằng Gem. Các gói thành viên và tính năng tạo không giới hạn trong ứng dụng không áp dụng cho các yêu cầu API. Tài khoản cần có một lần thanh toán thành công trước, có thể là bất kỳ gói Gem hoặc gói thành viên nào; Gem thưởng khi đăng ký chỉ dùng được trong ứng dụng Mage.
Tôi có thể dùng kết quả từ API cho mục đích thương mại không?
Có. Bạn có thể dùng nội dung tạo bằng Mage, kể cả qua API và máy chủ MCP, cho mục đích thương mại. Ghi nguồn thì chúng tôi rất trân trọng nhưng không bắt buộc.

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.

CharactersCộng đồng