Skip to content

认证与令牌 ​

令牌格式 ​

妙图设计 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 头中携带令牌:

http
Authorization: Bearer tsk_live_你的令牌

curl 示例:

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

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

缺少 Authorization、令牌无法识别、已吊销,或令牌上的过期时间已到,HTTP 状态都是 401,响应体相同:

json
{
  "code": 401,
  "msg": "账号未登录",
  "data": null
}

令牌有效但没有该接口的 Scope 时,HTTP 状态是 403:

json
{
  "code": 403,
  "msg": "没有该操作权限",
  "data": null
}

这两种情况都不要重试。查询别人的任务时,body 里的 code 也是 403、msg 也是「没有该操作权限」,但 HTTP 状态是 200,详见错误处理。


权限范围(Scope) ​

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

Scope 规范名称接受的别名可访问接口
account—GET /account/balance
tasks—GET /tasks/{taskId}
text2image—POST /image/text2image
matting—POST /image/matting
style_transformstyle-transformPOST /image/style-transform
inpainting—POST /image/inpainting
super_resolutionsuper-res, super_resPOST /image/super-resolution
clarify—POST /image/clarify
outpainting—POST /image/outpainting
smart_editsmart-editPOST /image/smart-edit
local_replacelocal-replacePOST /image/local-replace
remove_watermarkremove-watermarkPOST /image/remove-watermark
remove_wrinkleremove-wrinklePOST /image/remove-wrinkle
to_svg2svgPOST /image/to-svg/v2,兼容 POST /image/to-svg
to_grayscale2grayscalePOST /image/to-grayscale
variation—POST /image/variation
extract_printingextract-printingPOST /image/extract-printing
svg2dxf—POST /image/svg2dxf
mockup—POST /image/mockup、GET /image/mockup
head_stickerhead-stickerPOST /image/head-sticker
upload—POST /images/upload
page—GET /images/page
*—所有接口(含 DELETE /images/{id})

DELETE /images/{id} 的路径末段是数字 ID,当前鉴权按路径末段解析 Scope,因此删除图片请使用 *。已停用的 POST /image/style-transfer 不再发放 style_transfer Scope。

最小权限示例:

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

若令牌缺少所需 Scope,接口返回上面的 HTTP 403。


令牌过期与吊销 ​

  • 创建时若不填过期时间,令牌不会自动过期。若设置了过期时间且已过,请求返回上面的 HTTP 401。
  • 可在 账户 → API 密钥 页面随时手动吊销令牌。
  • 吊销后,使用该令牌的请求返回上面的 HTTP 401(code: 401,msg:「账号未登录」)。

令牌安全最佳实践 ​

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

令牌泄漏应急处理 ​

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

妙图设计 API Beta