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

Mage SDK · TypeScript

Mage TypeScript SDK

สร้างภาพ วิดีโอ และเสียงด้วย AI จาก Node.js พร้อมค่ากำหนดแบบมีไทป์สำหรับทุกโมเดลของ Mage เรียกครั้งเดียวก็ส่งคำขอ รอ และคืนผลลัพธ์ให้

npm install @mage-space/sdk

ดูแบบเร็ว ๆ

Mage TypeScript SDK คือไคลเอนต์โอเพนซอร์สอย่างเป็นทางการสำหรับ Mage API เผยแพร่ในชื่อ @mage-space/sdk ติดตั้งด้วย "npm install @mage-space/sdk" ตั้งค่า MAGE_API_KEY แล้วเรียก mage.run พร้อมรหัสโมเดลและคอนฟิก เพื่อรับภาพ วิดีโอ หรือเสียงที่เสร็จแล้วจากโมเดลใดก็ได้ใน 37 โมเดล ใช้งานได้บน Node.js 20.19 ขึ้นไป หรือรันไทม์ฝั่งเซิร์ฟเวอร์ใดก็ตามที่มี fetch และจ่ายทุกการสร้างด้วย Gems

  • 20.19+Node.js
  • 0Dependency ตอนรันไทม์
  • 37โมเดลแบบ typed
  • MITโอเพนซอร์ส

การตั้งค่า

ติดตั้ง TypeScript SDK และรันโมเดล

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

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

    npm install @mage-space/sdk
  2. ตั้งค่า API key

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

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

    เรียก run พร้อม id ของโมเดลและค่ากำหนด ระบบจะรอผลลัพธ์แล้วส่งกลับมา โดยไฟล์ผลลัพธ์อยู่ที่ 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);

ตัวอย่าง

TypeScript SDK ในการใช้งานจริง

ทุกตัวอย่างเริ่มจากไคลเอนต์ที่อ่านค่า MAGE_API_KEY

ส่งตอนนี้ รอทีหลัง
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),
});
อัปโหลดไฟล์
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],
});
ใช้ตัวละครที่บันทึกไว้
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' });
จัดการข้อผิดพลาด
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;
  }
}

ทำไมต้องใช้ SDK

สิ่งที่ SDK จัดการให้คุณ

  • เรียกครั้งเดียว ได้สื่อที่เสร็จสมบูรณ์

    run จะส่งคำสั่งสร้าง โพลด้วย backoff ตามที่ API แนะนำ และคืนคำขอที่เสร็จสมบูรณ์พร้อม result.url

  • ลองใหม่โดยไม่เสียเงินซ้ำ

    ทุกการส่งงานมี idempotency key หากเกิดข้อผิดพลาดของเครือข่ายหรือเซิร์ฟเวอร์ ระบบจะลองใหม่ด้วย backoff และการส่งงานซ้ำจะไม่ถูกเรียกเก็บเงินอีก

  • อัปโหลดในครั้งเดียว

    ไฟล์ที่ใหญ่เกินกว่าจะใช้ data URL จะอัปโหลดผ่านลิงก์ที่ลงนามไว้ โดย SDK จัดการทั้งตั๋วอัปโหลด การ PUT และการตรวจขนาดไฟล์ให้

  • ข้อผิดพลาดที่เข้าใจง่าย

    เมื่อ API ปฏิเสธคำขอ จะมี HTTP status, รหัสข้อผิดพลาด และ request id ให้ครบ ส่วนการสร้างที่ล้มเหลวหรือถูกยกเลิก และการหมดเวลา ก็มีประเภทข้อผิดพลาดของตัวเอง

  • มีไทป์ครบทุกโมเดล

    MangoConfig, CherryConfig และตัวอื่น ๆ สร้างขึ้นจากเอกสารอ้างอิง API ตัวแก้ไขโค้ดของคุณจึงช่วยเติมฟิลด์และจับตัวเลือกที่ไม่ถูกต้องได้

  • ไม่มี dependency

    เป็น ESM ที่ไม่มี dependency ตอนรันไทม์ ใช้ fetch ที่มีมาในตัว Node.js และทุกการเรียกรับ AbortSignal ได้

เอกสารอ้างอิง

TypeScript 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

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

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

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

ใช้ Mage TypeScript SDK ในเบราว์เซอร์ได้ไหม
ไม่ได้ API key ใช้จ่ายด้วย Gems ของคุณ จึงควรเก็บไว้บนเซิร์ฟเวอร์ของคุณเท่านั้น API ไม่ส่งเฮดเดอร์ CORS เบราว์เซอร์จึงเรียกโดยตรงไม่ได้ ให้เรียกแบ็กเอนด์ของคุณเอง แล้วให้แบ็กเอนด์ใช้ SDK แทน
TypeScript SDK ใช้กับ CommonJS ได้ไหม
แพ็กเกจนี้เป็น ESM เท่านั้น แต่ Node.js 20.19 ขึ้นไปสามารถ require() จาก CommonJS ได้เช่นกัน
TypeScript SDK ใช้กับ Next.js ได้ไหม
ได้ ในโค้ดฝั่งเซิร์ฟเวอร์ เช่น route handler และ server action SDK สร้างบน fetch และ Web API มาตรฐานอย่าง AbortSignal รันไทม์ฝั่งเซิร์ฟเวอร์อื่นที่มี fetch จึงน่าจะใช้ได้เช่นกัน แต่ CI ทดสอบบน Node.js
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ชุมชน