身份验证

身份验证

API Key

  • تمامی فراخوانی‌های API نیازمند احراز هویت با کلید API هستند.کلید API باید در هدر تمام درخواست‌ها ارسال شود:

دریافت کلید API

مراحل دریافت کلید API:

۱. وارد داشبورد MuAPI شوید. ۲. وارد حساب خود شده یا حساب جدید ایجاد کنید. ۳. به صفحه کلیدهای دسترسی (API Keys) بروید. ۴. یک کلید API جدید ایجاد کنید. ۵. کلید تولید شده را کپی کرده و در محل امنی ذخیره نمایید.

کلیدهای تستی (Sandbox) در برابر کلیدهای عملیاتی (Production)

هنگام ساخت کلید می‌توانید نوع آن را Sandbox (تستی) انتخاب کنید:

  • **کلیدهای عملیاتی: ** کلیدهای اصلی که وظایف واقعی را با مصرف اعتبار پردازش می‌کنند.
  • **کلیدهای تستی: ** کلیدهای علامت‌گذاری شده با نشان Sandbox که برای تست رایگان بازگشت فوری داده‌های شبیه‌سازی شده به کار می‌روند.

[!TIP] در طول مراحل توسعه از کلید Sandbox استفاده کنید تا از کسر ناخواسته اعتبار جلوگیری شود.

احراز هویت OAuth 2.0 (برای عامل‌ها و کلاینت‌های نرم‌افزاری)

对于 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 小时后过期，过期后重新申请。

دامنه‌های دسترسی مجاز (Scopes) — 通过 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));
身份验证 — Muapi Docs