安裝
驗證
從 developer settings 產生一把 key，把它作為 AISTEMSPLITTER_API_KEY 放進環境變數，並傳給 client constructor。SDK 不會記錄這把 key，頁面也只會在 tooltip 中顯示 public-safe 的 ast_live_ 前綴。
import { AiStemSplitter } from "@aistemsplitter/sdk";
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});Hello world
12 行，端到端。提交音軌，等待 htdemucs_ft 模型完成，然後把四條 stem——vocals、drums、bass、other——寫到磁碟。貼進單一 .mjs 檔，設定 key，在站會 demo 前跑起來。
import { AiStemSplitter } from "@aistemsplitter/sdk";
import { writeFile } from "node:fs/promises";
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});
// 1. Submit a split job
const job = await client.createSplit({
input: { type: "direct_url", url: "https://example.com/song.mp3" },
stemModel: "htdemucs_ft",
});
// 2. Wait until completion (polls under the hood)
const result = await client.waitForSplit(job.id);
// 3. Download all six stems
for (const [name, url] of Object.entries(result.stems)) {
const audio = await fetch(url).then((r) => r.arrayBuffer());
await writeFile(`./${name}.wav`, Buffer.from(audio));
}Methods
6 個型別化 methods 覆蓋完整 job lifecycle。每一個都是已發布 package 上真實的 TypeScript signature——編輯器可自動補全，不用自己寫 fetch wrapper，也不用背 schema。
提交新的 split job；回傳 job id 和 queued status。
取得某個 split job 的目前狀態。
持續輪詢，直到 job 成功、失敗或超時。
依頁列出這把 API 金鑰最近的 split jobs。
取得 pre-signed PUT URL，用於瀏覽器/伺服器直接上傳。
驗證傳入 webhook payload 上的 HMAC-SHA256 signature。
Webhooks
輪詢能讓 demo 跑通。Webhooks 才能走向 production。把 signed callback URL 放進 createSplit，然後在現有 Express 或 Hono handler 中，用一次 SDK 呼叫驗證 HMAC-SHA256 signature。
import { AiStemSplitter } from "@aistemsplitter/sdk";
import { Hono } from "hono";
const app = new Hono();
const client = new AiStemSplitter({
apiKey: process.env.AISTEMSPLITTER_API_KEY!,
});
app.post("/webhooks/aistemsplitter", async (c) => {
const raw = await c.req.text();
const event = client.verifyWebhook(c.req.header(), raw); // throws if invalid
switch (event.type) {
case "split.succeeded":
// event.data.stems → six URLs
break;
case "split.failed":
// event.data.error → { code, message }
break;
}
return c.text("ok");
});FAQ
Does @aistemsplitter/sdk work in Bun and Deno without polyfills?
Yes. The package is dual-published to npm and JSR, so Bun installs via `bun add jsr:@aistemsplitter/sdk` and Deno via `deno add jsr:@aistemsplitter/sdk`. There are no @types/node polyfills, no Buffer shimming required, and no node:fs imports in the client core — the typed surface uses the Web Fetch + Web Streams APIs, which Node 18+, Bun, and Deno all implement natively.
How do I verify webhook signatures in Express, Hono, or Next.js?
Call ast.verifyWebhook({ headers, body }) — it computes the HMAC-SHA256 over the raw body, constant-time-compares against the aistemsplitter-signature header, and throws on tamper. The Webhooks section above shows runnable Express and Hono handlers; for Next.js App Router, use the Hono pattern in a route.ts handler with `await request.text()` to read the raw body before verification.
Is the TypeScript surface real, or `any` everywhere?
Real. Every method on AistemsplitterClient has a typed input + Promise return: createSplit(input: CreateSplitInput) → Promise<Split>, getSplit(id: string) → Promise<Split>, waitForSplit, listSplits, presignUpload, verifyWebhook. The Split + Stem + WebhookEvent types are exported from the package root, so you can import them into your own handlers and storage layer without re-deriving the shape.
How do I handle errors and retries from the SDK?
All methods throw typed errors: AistemsplitterApiError (4xx/5xx with code + message + requestId), AistemsplitterRateLimitError (429 with retryAfter seconds), AistemsplitterNetworkError (transport-level). waitForSplit retries polls automatically with exponential backoff until the SDK timeout (default 5 min) — wrap createSplit / presignUpload in your own retry helper if you need at-least-once submission semantics.
Can I run this in the browser?
No — the SDK is a server-side client. Browser use would expose your API key (any code that reaches the user's machine can read it) and run into CORS on the upload endpoints. Mint a short-lived signed URL on your server with presignUpload and hand only that URL to the browser; do the actual createSplit + waitForSplit calls from a server route, n8n workflow, or background worker.
@aistemsplitter/sdk 可以在 Bun 和 Deno 中不加 polyfill 運行嗎？
可以。這個 package 同時發布到 npm 和 JSR，所以 Bun 可透過 `bun add jsr:@aistemsplitter/sdk` 安裝，Deno 可透過 `deno add jsr:@aistemsplitter/sdk` 安裝。client core 中沒有 @types/node polyfills、不需要 Buffer shimming，也沒有 node:fs imports——型別化 surface 使用 Web Fetch + Web Streams APIs，Node 18+、Bun 和 Deno 都原生實作。
如何在 Express、Hono 或 Next.js 中驗證 webhook signatures？
呼叫 ast.verifyWebhook({ headers, body })——它會基於 raw body 計算 HMAC-SHA256，和 aistemsplitter-signature header 做 constant-time compare，並在被竄改時拋錯。上方 Webhooks 區塊展示可執行的 Express 和 Hono handlers；若是 Next.js App Router，請在 route.ts handler 中使用 Hono 模式，透過 `await request.text()` 讀取 raw body 後再驗證。
TypeScript surface 是真實型別，還是到處都是 `any`？
是真實型別。AistemsplitterClient 上每個 method 都有 typed input + Promise return：createSplit(input: CreateSplitInput) → Promise<Split>、getSplit(id: string) → Promise<Split>、waitForSplit、listSplits、presignUpload、verifyWebhook。Split + Stem + WebhookEvent types 從 package root 匯出，所以你可以把它們 import 到自己的 handlers 和 storage layer，不用重新推導 shape。
SDK 的錯誤和 retries 要怎麼處理？
所有 methods 都會拋出 typed errors：AistemsplitterApiError（4xx/5xx，帶 code + message + requestId）、AistemsplitterRateLimitError（429，帶 retryAfter seconds）、AistemsplitterNetworkError（transport-level）。waitForSplit 會自動用 exponential backoff retry 輪詢，直到 SDK timeout（預設 5 min）——如果需要 at-least-once submission 語意，請把 createSplit / presignUpload 包進你自己的 retry helper。
我可以在瀏覽器中執行它嗎？
不行——SDK 是 server-side client。瀏覽器使用會暴露你的 API key（任何到達使用者裝置的程式碼都能讀到它），也會遇到 upload endpoints 的 CORS 限制。請在你的 server 上用 presignUpload 建立 short-lived signed URL，只把這個 URL 交給瀏覽器；實際的 createSplit + waitForSplit 呼叫應放在 server route、n8n workflow 或 background worker 中。