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 key 上设置的路由模式，未设置时则使用模型默认值（即 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 请求头。使用相同的请求体再次发送相同的 Key 将返回原任务，而不是创建新任务。使用不同的请求体发送相同的 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"
}

Webhooks

在控制台 → 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_…）进行签名，该密钥仅在创建或轮换时显示一次。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 错误。