身份验证

身份验证

API Key

  • 所有 MuAPI AI API 都需要使用 API key 进行身份验证。所有 API 调用都必须在请求头中包含你的 API key：

获取 API Key

获取 API key：

  1. 前往 MuAPI AI 控制台。
  2. 登录账户，或创建新账户。
  3. 进入 API Keys 页面。
  4. 生成新的 API key。
  5. 复制并安全保存 API key。

沙盒 Key 与生产 Key

创建 Key 时，可以选择创建沙盒（测试）Key：

  • 生产 Key： 普通 Key，会消耗积分并处理真实任务。
  • 沙盒 Key： 控制台中带有 Sandbox 标记的特殊 Key，用于免费测试集成，并立即返回模拟数据。

[!TIP] 开发期间始终使用沙盒 Key，避免意外消耗积分。

OAuth 2.0（Agent 与机器客户端）

对于 Agent 和其他机器客户端，MuAPI 还支持 OAuth 2.0 的 client_credentials 授权模式 — 这是普通 API key 之外的一种有作用域、短时有效的凭据。当你希望将凭据交给第三方或自主 Agent，又不想授予其完整且不受限制的账户访问权限时，可以使用此模式。

  1. 创建 OAuth 客户端：调用 POST https://api.muapi.ai/oauth/clients。该请求需要会话身份验证 — 应从自己已登录的浏览器会话发起，而不是使用 API key，并提交 name 和希望授予的 scopes。接口会返回 client_id 和 client_secret；Secret 只显示一次，请像 API key 一样保存。
  2. 换取访问令牌：调用 POST https://api.muapi.ai/oauth/token，提交 grant_type=client_credentials、client_id、client_secret 以及可选的 scope（以空格分隔；默认使用该客户端被允许的全部作用域）。
  3. 将返回的 access_token 像 API key 一样使用：Authorization: Bearer <access_token>。令牌 1 小时后过期，过期后重新申请。

可用作用域 — 通过 GET /oauth/scopes 查看实时、机器可读的列表：

作用域权限
generate:write提交图像、视频、音频、3D 等生成请求并消耗积分。
generate:read轮询预测状态并获取输出。
files:write将媒体上传到 MuAPI 托管的存储。
account:read读取钱包余额、用量以及账户/方案信息。
keys:manage创建、列出和撤销 API key 与 OAuth 客户端。

客户端只能请求创建时授予它的作用域。你可以在单个令牌中请求比客户端完整 allowed_scopes 更窄的 scope，实现最小权限原则。例如，只为只读 Agent 授予 generate:read account:read。

使用 DELETE /oauth/clients/{id} 撤销客户端 — 这会立即使它的所有现有访问令牌失效，而不必等到令牌自身的 1 小时有效期结束。

OAuth 客户端库和 Agent 扫描器所需的发现元数据发布在： https://muapi.ai/.well-known/oauth-authorization-server（RFC 8414）和 https://muapi.ai/.well-known/oauth-protected-resource（RFC 9728）。

[!NOTE] 这只支持机器到机器的身份验证 — 没有用户登录/授权同意界面（authorization_code 授权模式）。如果你要为终端用户构建“使用 Muapi 登录”流程，目前还不支持。

安全最佳实践

  • 永远不要分享 API key： 妥善保密。
  • 不要将 API key 硬编码： 使用环境变量或安全的密钥管理系统。
  • 定期轮换 Key： 定期生成新的 API key，并停用旧 Key。
  • 使用受限 Key： 条件允许时，创建权限受限的 Key。
  • 妥善保存： API key 只会显示一次，请复制并安全存储。之后无法再次找回。

使用示例

1. cURL

curl --location --request POST 'https://muapi.ai/api/v1/endpoint' \
--header "Content-Type: application/json" \
--header "x-api-key: {MUAPIAPP_API_KEY}" \
--data-raw '{"param1": "value1", "param2": "value2"}

2. Python

import requests
import json

headers = {
  "x-api-key": f"{MUAPIAPP_API_KEY}",
  "Content-Type": "application/json"
}

payload = {
  "param1": "value1",
  "param2": "value2"
}

response = requests.post("https://api.muapi.ai/api/v1/endpoint",   json=payload, headers=headers)
print(response.json())

3. Javascript

const apiKey = process.env.MUAPIAPP_API_KEY;

const headers = {
  'x-api-key': `${apiKey}`,
  'Content-Type': 'application/json'
};

const payload = {
  param1: 'value1',
  param2: 'value2'
};

fetch('https://muapi.ai/api/v1/endpoint', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
身份验证 — Muapi Docs