MLMux API

快速入門

1. 01

   建立 API 金鑰

   在主控台 → API 金鑰中建立金鑰。完整的金鑰只會顯示一次，請立即妥善儲存，例如設為 MLMUX_API_KEY。

2. 02

   發送請求

   使用模型 ID 和提示詞呼叫圖片或影片端點。費用將計入持有該金鑰的帳號。

3. 03

   取得結果

   圖片請求會在回應中傳回 URL。影片請求則會傳回任務：請輪詢其 poll_url 或訂閱 webhook。

身份驗證

對 https://api.mlmux.com 發送的每個請求，都必須在 Authorization: Bearer 標頭中帶入您的金鑰。金鑰以 sk- 開頭。API 不接受其他標頭或查詢字串中的金鑰。

若要檢查金鑰是否正常運作，請列出其可呼叫的模型：

curl https://api.mlmux.com/v1/models \
  -H "Authorization: Bearer $MLMUX_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "nano-banana-2", "object": "model", "owned_by": "platform" },
    { "id": "model/seedance-2.5-max", "object": "model", "owned_by": "platform" }
  ]
}

端點

所有端點均位於 https://api.mlmux.com 下。除非另有說明，否則請求和回應主體均為 JSON。

路由模式

在請求主體中設定 route_mode 即可選擇上游層級。請求會固定在其層級內，絕不會在背後無預警轉移至其他層級；若該模型已停用該層級，請求將失敗並回傳 route_mode_disabled。若省略此欄位，MLMux 會使用 API 金鑰所設定的路由模式，若無設定則採用模型預設值（即 official-cheap）。

計費方式

用量以點數計費，1 點等於 1 美元。影片模型依輸出 token 計費；圖片模型則依模型不同，按上游 token 或按張計費。各路由費率請參閱定價頁面。

任務回應在建立時會顯示 estimated_charge_credits，成功後會顯示 actual_charge_credits，兩者單位皆為點數。Webhook 酬載則會以整數顯示 actual_charge_nano_credits，其中 1,000,000,000 nano-credits 等於 1 點。

使用 GET /v1/account/balance 查詢您的剩餘餘額。

任務與輪詢

影片請求以及帶有 "async": true 的圖片請求，均會傳回 HTTP 202 及任務物件。請每隔幾秒輪詢該任務的 poll_url，直到其狀態變更為 succeeded、failed、expired 或 canceled。

取消任務

處於 queued、submitted 或 running 狀態的任務均可取消，並將釋放其預扣的點數。回應為 {"id": "task_…", "status": "canceled"}。處於任何其他狀態的任務將傳回 409 task_not_cancelable。

安全重試

非同步影片與圖片生成請求接受最多 160 個字元的 Idempotency-Key 標頭。使用相同內容再次發送相同金鑰將返回原始任務，而不是建立新任務。使用不同內容發送相同金鑰將返回 409 idempotency_key_reused。同步請求與圖片編輯不接受此標頭。

上傳

若要使用本機檔案作為參考，請將其以 multipart 欄位 file 上傳。支援最大 50 MB 的圖片、影片和音訊，並保留 3 天。在生成請求的任何 URL 欄位中傳入返回的 url。

curl https://api.mlmux.com/v1/uploads \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -F "file=@start-frame.jpg"

{
  "url": "https://.../uploads/3f8a....jpg",
  "asset_id": 1024,
  "mime_type": "image/jpeg",
  "size_bytes": 482113,
  "asset_type": "image"
}

Webhook

在控制台 → Webhook中建立端點並選擇要接收的事件。當請求或任務完成時，MLMux 會向您的 URL 發送帶有 JSON 內文的 POST 請求。

{
  "event_id": "evt_5b0d...",
  "event_type": "request.succeeded",
  "created_at": "2026-10-26T08:00:00Z",
  "data": {
    "request_id": "task_task_01a9...",
    "task_id": "task_01a9...",
    "public_model_id": "model/seedance-2.5-max",
    "api_method": "videos.generations.create",
    "image_count": 0,
    "image_resolution": "",
    "video_seconds": 8,
    "video_resolution": "720p",
    "actual_charge_nano_credits": 1790000000,
    "latency_ms": 94210
  }
}

驗證簽章

每次傳送都會使用端點的簽章密鑰（whsec_…）進行簽署，該密鑰會在您建立或輪換時顯示一次。X-MLMux-Signature 標頭包含 Unix 時間戳記 t 和簽章 v1：時間戳記、句點及原始請求內文的十六進位 HMAC-SHA256。計算相同的值進行比對，並拒絕過期時間戳記。

import crypto from "node:crypto";

// header: X-MLMux-Signature: t=1767225600,v1=5f8c...
export function verifyMLMuxSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

請在 10 秒內返回任何 2xx 狀態。MLMux 會在約 11 小時內最多重試發送 6 次。使用 X-MLMux-Event-ID 來忽略重複傳送的事件。

錯誤

錯誤均採用相同的 JSON 格式。請根據 code 而非 message 進行分支處理。聯絡支援團隊時，請提供 request_id（此資訊也會在 X-Request-ID 標頭中返回）。

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "request_id": "req_9f2c..."
  }
}

429 回應包含 Retry-After 標頭。請等待該秒數後再重試，並使用指數退避重試 5xx 錯誤。