API 参考

MuAPI 遵循简单的“提交任务 → 轮询结果”模式。所有端点都位于 https://api.muapi.ai/api/v1 下。

身份验证

每个请求都要包含你的 API key：

x-api-key: YOUR_API_KEY

从控制台 → API Keys获取 API key。

请求模式

1. 提交任务

POST https://api.muapi.ai/api/v1/{endpoint}
x-api-key: YOUR_API_KEY
Content-Type: application/json

{ ...model-specific parameters... }

响应：

{
  "request_id": "abc123xyz",
  "status": "processing",
  "cost": {
    "amount_usd": 0.0042,
    "amount_credits": 1,
    "bonus_credits_used": 0,
    "refunded": false
  }
}

2. 轮询结果

GET https://api.muapi.ai/api/v1/predictions/{request_id}/result
x-api-key: YOUR_API_KEY

响应（已完成）：

{
  "id": "abc123xyz",
  "status": "completed",
  "outputs": ["https://cdn.muapi.ai/...output.png"],
  "cost": {
    "amount_usd": 0.0042,
    "amount_credits": 1,
    "bonus_credits_used": 0,
    "refunded": false
  }
}

单次请求成本

每个提交和结果响应都包含本次请求实际扣除的钱包费用，因此无需在外部查找定价表：

字段类型含义
amount_usdfloat以美元计的扣费金额（已应用赠送积分和折扣）。
amount_creditsint以 MuAPI 积分表示的相同扣费。
bonus_credits_usedint从赠送积分池（Suno、Seedance 等）中支付的部分。
refundedbool仅当失败任务已经退款后才为 true。

每个 /api/v1/* 响应也会返回这些响应头，因此 Agent 无需解析响应体即可读取成本：

X-MuAPI-Cost-USD:           0.004200
X-MuAPI-Cost-Credits:       1
X-MuAPI-Cost-Bonus-Credits: 0       (仅在非零时返回)
X-MuAPI-Cost-Refunded:      true    (仅在已退款时返回)
X-Account-Balance:          18.7234 (剩余钱包余额，美元)

状态值

状态描述
queued任务等待开始
pending任务已接受，但尚未运行
processing正在生成
completed输出已准备好
failed生成失败
cancelled任务已取消

账户端点

# 查询余额
GET /api/v1/account/balance

# 充值积分
POST /api/v1/account/topup
{ "amount": 20 }

API Key 管理

# 列出 Keys
GET /api/v1/keys

# 创建 Key
POST /api/v1/keys
{
  "name": "my-app",
  "is_test": true
}

删除 Key

DELETE /api/v1/keys/{key_id}

沙盒（测试）模式

沙盒模式可以在不消耗积分、也不执行真实后台任务的情况下测试集成。

功能

  • 零成本： 不会从账户扣除积分。
  • 即时响应： 任务会立即使用模拟数据完成。
  • 没有副作用： 不会触发后台 Worker，不会执行真实生成。

使用方式

  1. 通过 API 创建带有 is_test=true 的 Key，或在控制台勾选 Sandbox。
  2. 在任意“提交 → 轮询”流程中使用该 Key。
  3. API 会立即返回成功的模拟响应。

不同模型类型的行为

  • 图像： 返回模型的示例/缩略图 URL。
  • 视频/音频： 返回模型的示例媒体 URL。

文件上传

上传媒体作为输入：

POST /api/v1/upload_file
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data

file=@image.jpg

接口会返回托管 URL，可在生成请求中作为 image_url 传入。

OpenAPI 规范

完整的机器可读规范位于：

GET https://api.muapi.ai/openapi.json

也可以通过 CLI 获取：

muapi docs openapi
muapi docs open

另请参阅