ข้ามไปยังเนื้อหา

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 และรันโมเดล

  1. ติดตั้งแพ็กเกจ

    เพิ่ม mage-space ลงในโปรเจกต์ของคุณ

    pip install mage-space
  2. ตั้งค่า API key

    สร้างคีย์ที่ API → API Keys บน mage.space แล้ว export ไว้ ไคลเอนต์จะอ่านค่าจาก MAGE_API_KEY

    export MAGE_API_KEY="mage_sk_..."
  3. สร้าง

    เรียก 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()แคตตาล็อกโมเดลล่าสุดพร้อมตัวเลือกและราคา

โมเดล

เริ่มต้นกับโมเดลเหล่านี้

  • ภาพ · เริ่มต้น 37 Gems

    Guava API

    ภาพสมจริงราวกับภาพถ่ายจริง

  • ภาพ · เริ่มต้น 42 Gems

    Mango API

    โมเดลภาพรุ่นเรือธงของเรา

  • รูปภาพ · เริ่มต้น 51 Gems

    Nano Banana 2 API

    ข้อความคมชัด อ่านง่าย สูงสุด 4K

  • วิดีโอ · เริ่มต้น 618 Gems

    Cherry API

    โมเดลวิดีโอรุ่นเรือธงของเรา

  • วิดีโอ · เริ่มต้น 245 Gems

    Lemon API

    ครบทุกฟีเจอร์วิดีโอ ในราคาที่เป็นมิตรกว่า

  • เสียง · เริ่มต้น 19 Gems

    Seed Audio API

    เสียงพูด เพลง และเอฟเฟกต์เสียงจากพรอมต์เดียว

คำถามที่พบบ่อย

คำถามที่พบบ่อย

Python SDK รองรับ asyncio ไหม
รองรับ AsyncMage มีเมธอดเหมือนกับ Mage แต่ใช้ด้วย await และใช้เป็น async context manager ได้
SDK รองรับ Python เวอร์ชันไหนบ้าง
Python 3.10 ขึ้นไป มี dependency เพียง httpx และ typing-extensions
ใช้ Python SDK ในโน้ตบุ๊กหรือไปป์ไลน์ข้อมูลได้ไหม
ได้ ใช้ Mage ในสคริปต์และโน้ตบุ๊ก หรือใช้ AsyncMage กับ asyncio เพื่อสร้างหลายงานพร้อมกัน บัญชีหนึ่งรันได้พร้อมกันสูงสุด 20 งาน
Mage SDK ใช้ฟรีและเป็นโอเพนซอร์สหรือไม่
ใช่ SDK และโหนด ComfyUI เป็นโอเพนซอร์สภายใต้สัญญาอนุญาต MIT บน GitHub และติดตั้งได้ฟรี คุณจ่ายเฉพาะการสร้างที่รันจริง เป็น Gems ตามราคาที่แสดงไว้ของแต่ละโมเดล
โมเดล Mage ใหม่ใช้กับ SDK เวอร์ชันเก่าได้ไหม
ได้ แค่ส่ง id ของโมเดลใหม่เป็นสตริงก็รันได้เลย โดย SDK จะตรวจสอบค่ากำหนดกับฟิลด์ที่ทุกโมเดลใช้ร่วมกัน บอตจะอัปเดตไทป์ทุกครั้งที่เอกสารอ้างอิง API เปลี่ยน โมเดลใหม่จึงมาพร้อมไทป์ของตัวเองในรุ่นถัดไป
SDK ป้องกันการจ่ายเงินซ้ำเมื่อลองส่งคำขอใหม่ได้อย่างไร
ทุกคำขอที่ส่งจะมี Idempotency-Key SDK จะสร้างคีย์ใหม่ในแต่ละการเรียก และใช้คีย์เดิมเมื่อลองเรียกนั้นซ้ำเอง ดังนั้นการส่งซ้ำจะได้คำขอเดิมกลับมาและไม่มีการเรียกเก็บเงินเพิ่ม
SDK เสถียรหรือยัง
ตอนนี้เป็นเวอร์ชันเบต้า 0.x จึงอาจมีการเปลี่ยนแปลงในเวอร์ชันย่อยได้ ส่วน API เองแยกเวอร์ชันต่างหากและจะคงที่ภายใน v1
Mage API ราคาเท่าไร
ไม่มีค่าสมาชิกหรือค่ารายเดือน การสร้างแต่ละครั้งจ่ายเป็น Gems ตามราคาของโมเดลนั้น โดย 1,000 Gems ราคา $1 ในแพ็กมาตรฐาน หน้าโมเดลทุกหน้าแสดงราคาตามการตั้งค่าเริ่มต้น และผลลัพธ์ของแต่ละคำขอจะระบุยอดที่เรียกเก็บจริง หากการสร้างล้มเหลวจะได้รับเงินคืน แต่หากถูกบล็อกโดยนโยบายเนื้อหาของ Mage จะไม่คืนให้ หากยอดคงเหลือไม่พอสำหรับคำขอ ระบบจะปฏิเสธก่อนเรียกเก็บเงินใดๆ
ต้องเป็นสมาชิก Mage ถึงจะใช้ API ได้ไหม
ไม่ได้ API ใช้งานด้วย Gems เท่านั้น แผนสมาชิกและสิทธิ์สร้างไม่จำกัดในแอปไม่ครอบคลุมคำขอ API นอกจากนี้บัญชีต้องชำระเงินสำเร็จอย่างน้อยหนึ่งครั้งก่อน ไม่ว่าจะเป็นแพ็ก Gem หรือแผนใดก็ได้ โดย Gems โบนัสจากการสมัครใช้ได้ในแอป Mage เท่านั้น
นำผลลัพธ์จาก API ไปใช้เชิงพาณิชย์ได้ไหม
ได้ คอนเทนต์ที่คุณสร้างด้วย Mage รวมถึงที่สร้างผ่าน API และเซิร์ฟเวอร์ MCP นำไปใช้เชิงพาณิชย์ได้ ยินดีหากให้เครดิต แต่ไม่จำเป็น

เริ่มสร้างสรรค์ด้วย Mage

หนึ่งบัญชี หนึ่งยอด Gems ใช้ได้ทุกโมเดล จ่ายเฉพาะที่สร้างจริง

Charactersชุมชน