Mage SDK · Python
Mage Python SDK
สร้างภาพ วิดีโอ และเสียงด้วย AI จาก Python ผ่านไคลเอนต์แบบ sync และ asyncio พร้อมคอนฟิกแบบ typed สำหรับทุกโมเดลของ Mage
pip install mage-spaceดูแบบเร็ว ๆ
Mage Python SDK คือไคลเอนต์โอเพนซอร์สอย่างเป็นทางการสำหรับ Mage API เผยแพร่ในชื่อ mage-space ติดตั้งด้วย "pip install mage-space" ตั้งค่า MAGE_API_KEY แล้วเรียก mage.run พร้อมรหัสโมเดลและคอนฟิก เพื่อรับภาพ วิดีโอ หรือเสียงที่เสร็จแล้วจากโมเดลใดก็ได้ใน 37 โมเดล ใช้งานได้บน Python 3.10 ขึ้นไป และจ่ายทุกการสร้างด้วย Gems
- 3.10+Python
- httpxHTTP client
- 37โมเดลแบบ typed
- MITโอเพนซอร์ส
การตั้งค่า
ติดตั้ง Python SDK และรันโมเดล
ติดตั้งแพ็กเกจ
เพิ่ม mage-space ลงในโปรเจกต์ของคุณ
pip install mage-spaceตั้งค่า API key
สร้างคีย์ที่ API → API Keys บน mage.space แล้ว export ไว้ ไคลเอนต์จะอ่านค่าจาก MAGE_API_KEY
export MAGE_API_KEY="mage_sk_..."สร้าง
เรียก run พร้อม id ของโมเดลและค่ากำหนด ระบบจะรอผลลัพธ์แล้วส่งกลับมา โดยไฟล์ผลลัพธ์อยู่ที่ 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"])
ตัวอย่าง
Python SDK ในการใช้งานจริง
ทุกตัวอย่างเริ่มจากไคลเอนต์ที่อ่านค่า MAGE_API_KEY
ส่งตอนนี้ รอทีหลัง
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"]),
)อัปโหลดไฟล์
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"]],
})ใช้ตัวละครที่บันทึกไว้
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"})จัดการข้อผิดพลาด
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)ทำไมต้องใช้ SDK
สิ่งที่ SDK จัดการให้คุณ
เรียกครั้งเดียว ได้สื่อที่เสร็จสมบูรณ์
run จะส่งคำสั่งสร้าง โพลด้วย backoff ตามที่ API แนะนำ และคืนคำขอที่เสร็จสมบูรณ์พร้อม result.url
ลองใหม่โดยไม่เสียเงินซ้ำ
ทุกการส่งงานมี idempotency key หากเกิดข้อผิดพลาดของเครือข่ายหรือเซิร์ฟเวอร์ ระบบจะลองใหม่ด้วย backoff และการส่งงานซ้ำจะไม่ถูกเรียกเก็บเงินอีก
อัปโหลดในครั้งเดียว
ไฟล์ที่ใหญ่เกินกว่าจะใช้ data URL จะอัปโหลดผ่านลิงก์ที่ลงนามไว้ โดย SDK จัดการทั้งตั๋วอัปโหลด การ PUT และการตรวจขนาดไฟล์ให้
ข้อผิดพลาดที่เข้าใจง่าย
เมื่อ API ปฏิเสธคำขอ จะมี HTTP status, รหัสข้อผิดพลาด และ request id ให้ครบ ส่วนการสร้างที่ล้มเหลวหรือถูกยกเลิก และการหมดเวลา ก็มีประเภทข้อผิดพลาดของตัวเอง
Sync และ asyncio
Mage และ AsyncMage มีเมธอดเหมือนกันทุกตัว ไคลเอนต์แบบ async เหมาะกับเว็บเซิร์ฟเวอร์ โน้ตบุ๊ก และไปป์ไลน์ที่สร้างหลายงานพร้อมกัน
คอนฟิกแบบ typed
แต่ละโมเดลมี TypedDict เช่น MangoConfig ซึ่งสร้างจากเอกสารอ้างอิง API ใส่ annotation ให้คอนฟิกด้วย TypedDict แล้วตัวตรวจสอบชนิดข้อมูลจะเช็กฟิลด์ให้คุณ
เอกสารอ้างอิง
Python 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
โมเดลภาพรุ่นเรือธงของเรา
Nano Banana 2 API
ข้อความคมชัด อ่านง่าย สูงสุด 4K
Cherry API
โมเดลวิดีโอรุ่นเรือธงของเรา
Lemon API
ครบทุกฟีเจอร์วิดีโอ ในราคาที่เป็นมิตรกว่า
Seed Audio API
เสียงพูด เพลง และเอฟเฟกต์เสียงจากพรอมต์เดียว
คำถามที่พบบ่อย
คำถามที่พบบ่อย
Python SDK รองรับ asyncio ไหม
SDK รองรับ Python เวอร์ชันไหนบ้าง
ใช้ Python SDK ในโน้ตบุ๊กหรือไปป์ไลน์ข้อมูลได้ไหม
Mage SDK ใช้ฟรีและเป็นโอเพนซอร์สหรือไม่
โมเดล Mage ใหม่ใช้กับ SDK เวอร์ชันเก่าได้ไหม
SDK ป้องกันการจ่ายเงินซ้ำเมื่อลองส่งคำขอใหม่ได้อย่างไร
SDK เสถียรหรือยัง
Mage API ราคาเท่าไร
ต้องเป็นสมาชิก Mage ถึงจะใช้ API ได้ไหม
นำผลลัพธ์จาก API ไปใช้เชิงพาณิชย์ได้ไหม
เริ่มสร้างสรรค์ด้วย Mage
หนึ่งบัญชี หนึ่งยอด Gems ใช้ได้ทุกโมเดล จ่ายเฉพาะที่สร้างจริง