Mage SDK · Python
Python SDK của Mage
Tạo ảnh, video và âm thanh bằng Python với client đồng bộ và asyncio, cùng cấu hình có kiểu dữ liệu cho mọi mô hình của Mage.
pip install mage-spaceXem nhanh
Mage Python 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. Cài bằng "pip install mage-space", đặ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 Python 3.10 trở lên, và mỗi lần tạo đều trả bằng Gems.
- 3.10+Python
- httpxHTTP client
- 37Mô hình có định kiểu
- MITMã nguồn mở
Thiết lập
Cài đặt Python SDK và chạy một mô hình
Cài đặt gói
Thêm mage-space vào dự án của bạn.
pip install mage-spaceĐặ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.
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-v4", }) print(request["result"]["url"])
Ví dụ
Python SDK khi sử dụng 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
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
submitted = mage.generate("cherry", {
"prompt": "Waves rolling onto a black sand beach at sunset",
"resolution": "720p",
"duration": "5",
})
final = mage.requests.wait(
submitted["request_id"],
timeout=900,
on_update=lambda request: print(request["status"]),
)Tải tệp lên
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
clip = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
mage.run("cherry", {
"prompt": "Restyle this clip as a watercolor painting",
"videos": [clip["url"]],
})Dùng nhân vật đã lưu
from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
mage.characters.create(
name="Ana",
handle="ana",
image="https://example.com/ana.png",
)
mage.run("mango", {"prompt": "@ana walking through a night market"})Xử lý lỗi
from mage_space import Mage, MageAPIError, MageGenerationError
mage = Mage() # reads MAGE_API_KEY
try:
mage.run("mango", {"prompt": "A lighthouse at night"})
except MageAPIError as error:
if error.code == "insufficient_gems":
print("Gems needed:", error.body["error"]["gems_required"])
else:
raise
except MageGenerationError as error:
print("No output:", error.code)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.
Đồng bộ và asyncio
Mage và AsyncMage có chung mọi phương thức. Client bất đồng bộ phù hợp với máy chủ web, notebook và các pipeline chạy nhiều lượt tạo cùng lúc.
Cấu hình có kiểu dữ liệu
Mỗi mô hình có một TypedDict, chẳng hạn MangoConfig, được tạo từ tài liệu tham khảo API. Chú thích cấu hình bằng nó và trình kiểm tra kiểu sẽ kiểm tra các trường giúp bạn.
Tham khảo
Python SDK 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 một đường dẫn, bytes hoặc tệp dung lượng 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
Python SDK có hỗ trợ asyncio không?
SDK hỗ trợ những phiên bản Python nào?
Tôi có thể dùng Python SDK trong notebook hoặc pipeline dữ liệu 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.