认证与令牌

令牌格式

妙图设计 API 使用成员 API 令牌进行认证，格式为：

tsk_live_<22位 Base62 随机字符>

示例（占位符）：

tsk_live_A1b2C3d4E5f6G7h8I9j0Kl

公测标识：tsk_live_ 前缀表示当前为 Beta 公测令牌。GA 正式版的令牌格式可能调整，届时会提前公告。

---

如何创建令牌

1. 登录妙图，进入 账户 → API 密钥 页面。
2. 点击 创建令牌。
3. 填写令牌名称（便于识别用途，如 生产环境-服务A）。
4. 选择所需的权限范围（Scope）（见下文）。
5. 可选：设置月度积分上限，防止单令牌超支。
6. 点击确认后，明文令牌只展示一次。请立即复制并安全保存，关闭对话框后无法再次查看。

若令牌丢失，请直接吊销旧令牌并创建新令牌。

---

在请求中使用令牌

所有 API 请求须在 HTTP Authorization 头中携带令牌：

Authorization: Bearer tsk_live_你的令牌

curl 示例：

curl -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  "https://magiqsight.com/openapi/v1/account/balance"

令牌不能通过 URL 参数或请求体传递，仅支持 Authorization: Bearer 头。

---

权限范围（Scope）

每个令牌关联一组 Scope，决定该令牌能调用哪些接口。建议按最小权限原则分配。

Scope 规范名称	接受的别名	可访问接口
account	—	GET /account/balance
tasks	—	GET /tasks/{taskId}
text2image	—	POST /image/text2image
matting	—	POST /image/matting
style_transform	style-transform	POST /image/style-transform
inpainting	—	POST /image/inpainting
super_resolution	super-res, super_res	POST /image/super-resolution
clarify	—	POST /image/clarify
outpainting	—	POST /image/outpainting
smart_edit	smart-edit	POST /image/smart-edit
local_replace	local-replace	POST /image/local-replace
remove_watermark	remove-watermark	POST /image/remove-watermark
remove_wrinkle	remove-wrinkle	POST /image/remove-wrinkle
to_svg	2svg	POST /image/to-svg
to_grayscale	2grayscale	POST /image/to-grayscale
*	—	所有接口

最小权限示例：

• 仅用于文生图的令牌：选择 text2image + tasks（查询结果需要 tasks）。
• 读取余额的监控令牌：仅选择 account。
• 全功能令牌：选择 *。

若令牌缺少所需 Scope，接口返回 HTTP 403。

---

令牌过期与吊销

• 令牌不会自动过期（当前 Beta 版本）。
• 可在 账户 → API 密钥 页面随时手动吊销令牌。
• 吊销后立即生效，使用该令牌的请求会返回 HTTP 401（code: 1004013000）。

---

令牌安全最佳实践

实践	说明
使用环境变量	通过 $TUSEN_API_TOKEN 等环境变量传递令牌，不要硬编码到源代码
不提交到 Git	在 .gitignore 中排除包含令牌的配置文件；使用 .env.example 占位
不打印到日志	接口响应不含令牌明文，但不要在应用日志中打印 Authorization 头
不通过 URL 传递	URL 可能出现在服务器日志、浏览器历史和共享链接中
按用途分令牌	不同服务或环境使用不同令牌，出问题时可精确吊销
发现泄漏立即吊销	在 API 密钥页面吊销疑似泄漏的令牌，创建新令牌替换

---

令牌泄漏应急处理

1. 立即在 账户 → API 密钥 页面吊销泄漏的令牌。
2. 检查该令牌的近期调用记录，评估是否有异常消耗。
3. 用新令牌替换所有引用旧令牌的配置。
4. 若发现余额异常消耗，联系支持团队。