DEVELOPERS
公开 API · Webhook · 一目了然
所有公开数据都可以通过简洁的 REST 调用拿到;关键业务事件也可通过 Webhook 实时推送到你的服务。
API 端点
7
Webhook 事件
6
速率限制
按套餐
AUTHENTICATION
鉴权
所有 API 请求都必须携带 Authorization: Bearer mira_live_<prefix>_<secret>。Key 由系统在创建时一次性返回,后续不再展示;丢失只能撤销重发。
curl -s "https://example/api/v1/talents?status=live&limit=5" \ -H "Authorization: Bearer mira_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
ENDPOINTS
端点速查表
| 方法 | 路径 | 所需 scope | 说明 |
|---|---|---|---|
| GET | /api/v1/me | me:read | 查询当前 API Key 所属用户的基础信息与已授权 scope |
| GET | /api/v1/talents | talents:read | 列出形象,支持 ?status=live&tag=御姐&limit=20&offset=0 |
| GET | /api/v1/talents/{id} | talents:read | 形象详情(含 bio / 价格 / 分账) |
| GET | /api/v1/orders | orders:read | 列出我的订单(按 Key 主人身份自动过滤 partner/creator) |
| GET | /api/v1/orders/{id} | orders:read | 订单详情(含合同 / 交付包 ID) |
| POST | /api/v1/orders | orders:write | 创建订单(仅 partner 角色) body: { talentId, projectName, scope } |
| GET | /api/v1/webhooks | webhooks:read | 列出我订阅的 Webhook 与状态 |
CODE SAMPLES
代码示例
Node.js (POST 创建订单)
const res = await fetch("/api/v1/orders", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.MIRA_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ talentId: 1, projectName: "新品 TVC", scope: "全网授权 6 个月" }),
});
const json = await res.json();
console.log(json.data);Python (GET 形象列表)
import os, requests
r = requests.get(
"https://example/api/v1/talents",
headers={"Authorization": f"Bearer {os.environ['MIRA_KEY']}"},
params={"status": "live", "limit": 20},
)
print(r.json()["data"])WEBHOOKS
Webhook 事件
在 /me/webhooks 配置回调地址 + 关注事件,系统将以 JSON POST 推送;5 次失败后自动暂停。
order.paid
订单完成支付,推送给买卖双方
order.settled
订单结算入账
order.refunded
订单退款 / 仲裁支持制作方
talent.approved
形象通过审核进入选角广场
review.created
新增评价
verification.approved
用户完成实名
Webhook 请求头中 X-Mira-Signature 是 hex(hmacSha256(secret, rawBody)) ;请用同样算法在服务端比对,不一致即视为伪造。
校验签名 (Python)
import crypto, json
def verify(secret: str, raw_body: bytes, signature: str) -> bool:
mac = crypto.hmac.new(secret.encode(), raw_body, "sha256").hexdigest()
return crypto.compare_digest(mac, signature)ERRORS
错误约定
| HTTP | 含义 |
|---|---|
| 400 | 请求体或参数缺失 / 不合法 |
| 401 | 未携带 Authorization 或 Key 无效 / 已撤销 |
| 403 | Key 缺少所需 scope |
| 404 | 资源不存在 |
| 413 | 上传过大 |
| 500 | 服务器内部错误 |