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 キーに設定された route mode、次にモデルのデフォルトである official-cheap を使用します。

請求

利用料金はクレジットで請求され、1クレジットは1米ドルに相当します。動画モデルは出力トークン単位、画像モデルはモデルに応じてアップストリームのトークン単位または画像単位で課金されます。各ルートの料金については料金ページをご覧ください。

タスクレスポンスには、タスク作成時にestimated_charge_credits、成功後にactual_charge_creditsが表示されます（いずれもクレジット単位）。Webhookペイロードにはactual_charge_nano_creditsが整数で表示され、1,000,000,000ナノクレジットが1クレジットに相当します。

GET /v1/account/balanceで残高を確認できます。

タスクとポーリング

動画リクエスト、および"async": trueで送信された画像リクエストは、タスクとともにHTTP 202を返します。ステータスがsucceeded、failed、expired、またはcanceledになるまで、タスクのpoll_urlを数秒おきにポーリングしてください。

タスクのキャンセル

キュー中、送信済み、または実行中のタスクはキャンセル可能で、保留されていたクレジットは解放されます。レスポンスは{"id": "task_…", "status": "canceled"}になります。その他のステータスにあるタスクは409 task_not_cancelableを返します。

安全な再試行

非同期の動画および画像生成リクエストでは、最大160文字のIdempotency-Keyヘッダーを使用できます。同じキーと同じリクエストボディを再送すると、新規タスクを作成する代わりに元のタスクが返されます。同じキーで異なるリクエストボディを送信すると、409 idempotency_key_reusedが返されます。同期リクエストおよび画像編集ではこのヘッダーを受け付けません。

アップロード

ローカルファイルを参照として使用するには、マルチパートフィールド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

Console → Webhooksでエンドポイントを作成し、受信するイベントを選択します。リクエストまたはタスクが完了すると、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_…）で署名されます。これは作成時またはローテーション時に1度だけ表示されます。X-MLMux-SignatureヘッダーにはUnixタイムスタンプtと署名v1が含まれます。これはタイムスタンプ、ピリオド、生のリクエストボディの16進数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構造を持ちます。messageではなくcodeで分岐処理を行ってください。サポートにお問い合わせの際は、X-Request-IDヘッダーにも返されるrequest_idをお知らせください。

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

429レスポンスにはRetry-Afterヘッダーが含まれます。その秒数待機してから再試行し、5xxエラーは指数バックオフで再試行してください。