身份验证

身份验证

API Key

すべてのMuAPIエンドポイントはAPIキーによる認証が必要です。すべてのAPIリクエストのヘッダーにAPIキーを含める必要があります：

APIキーの取得

APIキーの取得手順：

MuAPIダッシュボードにアクセスします。
アカウントにログイン（または新規登録）します。
「API Keys」ページを開きます。
新しいAPIキーを発行します。
キーをコピーし、安全な場所に保管してください。

サンドボックスキーと本番キー

APIキー作成時にサンドボックス（テスト用）キーを選択できます：

本番キー： 通常のAPIキー。クレジットを消費して実際の生成処理を実行します。
サンドボックスキー： 無料で統合テストを行える特殊なキー。モックデータを即座に返却します。

[!TIP] 開発・テスト中はサンドボックスキーを使用することで、クレジットの無駄な消費を防止できます。

OAuth 2.0（Agent 与機器客户端）

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

創建 OAuth 客户端：调用 POST https://api.muapi.ai/oauth/clients。该请求需要会话身份验证 — 应从自己已登录的浏览器会话発起，而不是使用 API key，并提交 name 和希望授予的 scopes。接口会返回 client_id 和 client_secret；Secret 只显示一次，请像 API key 一样保存。
换取访問令牌：调用 POST https://api.muapi.ai/oauth/token，提交 grant_type=client_credentials、client_id、client_secret 以及可選的 scope（以空格分隔；默認使用该客户端被允许的全部作用域）。
将返回的 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キーを他人と共有しないでください： 厳重に秘密を保持してください。
不要将 API 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));