API Mage · SDK

SDK chính thức cho API Mage

Client có định kiểu cho TypeScript và Python, cùng các node Mage cho ComfyUI. Dùng mọi mô hình tạo ảnh, video và âm thanh chỉ với vài dòng code.

Lấy khóa APIĐọc tài liệu SDK

Xem nhanh

Mage phát hành các SDK mã nguồn mở cho API của mình: @mage-space/sdk trên npm cho TypeScript và JavaScript, mage-space trên PyPI cho Python, và bộ node comfyui-mage cho ComfyUI. Mỗi SDK bọc REST API với cấu hình có định kiểu cho cả 28 mô hình, tự động polling, thử lại idempotent và tải tệp lên.

Chọn SDK của bạn

SDK và tích hợp

npm install @mage-space/sdk

SDK TypeScript

Tạo ảnh, video và âm thanh từ Node.js với cấu hình có định kiể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ả.

pip install mage-space

SDK Python

Tạo ảnh, video và âm thanh từ Python với client đồng bộ và asyncio, cùng cấu hình có định kiểu cho mọi mô hình Mage.

comfy node install comfyui-mage

Mage cho ComfyUI

Mango, Cherry, Seed Audio và mọi mô hình khác của Mage dưới dạng node ComfyUI. Không cần GPU, không cần tải mô hình.

Bắt đầu nhanh

Lần tạo đầu tiên với SDK

Cài gói, xuất MAGE_API_KEY rồi chạy một mô hình.

TypeScript
// npm install @mage-space/sdk
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);
Python
# pip install mage-space
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-v3",
})

print(request["result"]["url"])

Tích hợp sẵn

Những việc SDK nào cũng lo 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.

Gói

Tải ở đâu

SDKGóiCài đặtMã nguồn
SDK TypeScript@mage-space/sdknpm install @mage-space/sdkGitHub
SDK Pythonmage-spacepip install mage-spaceGitHub
Mage cho ComfyUIcomfyui-magecomfy node install comfyui-mageGitHub

FAQ

Câu hỏi thường gặp

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 Gems. Các gói thành viên và quyền 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, nên bất kỳ tài khoản Mage nào có Gems đều có thể gọi API.

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.

Lấy khóa APIĐọc tài liệu SDK

Liên quan