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 และรันโมเดล
ติดตั้งแพ็กเกจ
เพิ่ม @mage-space/sdk ลงในโปรเจกต์ของคุณ
npm install @mage-space/sdkตั้งค่า API key
สร้างคีย์ที่ API → API Keys บน mage.space แล้ว export ไว้ ไคลเอนต์จะอ่านค่าจาก MAGE_API_KEY
export MAGE_API_KEY="mage_sk_..."สร้าง
เรียก 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() | แคตตาล็อกโมเดลล่าสุดพร้อมตัวเลือกและราคา |
โมเดล
เริ่มต้นกับโมเดลเหล่านี้
Guava API
ภาพสมจริงราวกับภาพถ่ายจริง
Mango API
โมเดลภาพรุ่นเรือธงของเรา
Nano Banana 2 API
ข้อความคมชัด อ่านง่าย สูงสุด 4K
Cherry API
โมเดลวิดีโอรุ่นเรือธงของเรา
Lemon API
ครบทุกฟีเจอร์วิดีโอ ในราคาที่เป็นมิตรกว่า
Seed Audio API
เสียงพูด เพลง และเอฟเฟกต์เสียงจากพรอมต์เดียว
คำถามที่พบบ่อย
คำถามที่พบบ่อย
ใช้ Mage TypeScript SDK ในเบราว์เซอร์ได้ไหม
TypeScript SDK ใช้กับ CommonJS ได้ไหม
TypeScript SDK ใช้กับ Next.js ได้ไหม
Mage SDK ใช้ฟรีและเป็นโอเพนซอร์สหรือไม่
โมเดล Mage ใหม่ใช้กับ SDK เวอร์ชันเก่าได้ไหม
SDK ป้องกันการจ่ายเงินซ้ำเมื่อลองส่งคำขอใหม่ได้อย่างไร
SDK เสถียรหรือยัง
Mage API ราคาเท่าไร
ต้องเป็นสมาชิก Mage ถึงจะใช้ API ได้ไหม
นำผลลัพธ์จาก API ไปใช้เชิงพาณิชย์ได้ไหม
เริ่มสร้างสรรค์ด้วย Mage
หนึ่งบัญชี หนึ่งยอด Gems ใช้ได้ทุกโมเดล จ่ายเฉพาะที่สร้างจริง