词汇表

本文档解释妙图设计 API 文档中使用的专业术语。

---

令牌（Token / API Token）

用于 API 认证的密钥字符串，格式为 tsk_live_<22位 Base62 字符>。
令牌代表特定用户的 API 访问凭证，携带权限范围（Scope）和月度积分上限设置。
在 账户 → API 密钥 页面创建和管理，明文只在创建时展示一次。

---

权限范围（Scope）

令牌被授权访问的接口集合。每个令牌在创建时绑定一组 Scope，用于最小权限访问控制。

示例：text2image、matting、*（全部权限）。

详见认证与令牌 → 权限范围。

---

积分（Point）

API 服务的计费单位。每次调用图像处理接口消耗 1 个 API_CALL 积分。
积分来源于账户充值，以批次形式存入，各批次有独立到期时间。
API 积分与前端产品图像积分相互独立。

详见积分与限速。

---

月度积分上限（Monthly Cap）

单个令牌在一个自然月内可消耗积分的最大值。超出上限后，该令牌的图像接口调用返回 HTTP 402（错误码 1004013001）。
月度上限在 账户 → API 密钥 页面针对每个令牌单独设置，不影响账户总余额。

---

异步任务（Async Task）

妙图图像接口的执行模式。提交请求后立即返回 taskId，任务在后台处理，结果通过轮询 GET /tasks/{taskId} 获取。
任务有 PENDING → PROCESSING → SUCCESS/FAILURE/CANCELLED 的生命周期。

详见异步任务。

---

taskId

标识一个图像处理任务的唯一字符串，由提交接口（如 POST /image/text2image）返回。
用于通过 GET /tasks/{taskId} 查询任务状态和结果。
当前 Beta 版本：taskId 为内部任务 ID。GA 版本将提供更稳定的公开 job_id 标识。

---

requestId

调用方在提交任务时自定义传入的唯一请求标识，可通过请求体字段 requestId 或 HTTP 头 X-Request-Id 传递。
作用：

• 随任务一起返回（在响应的 data.requestId 中）。
• 用于计费去重记录（不保证幂等重放）。
• 联系支持时用于日志追踪。

建议使用 UUID v4 格式，每次调用生成新值。

---

CommonResult（响应包装体）

妙图 API 的统一响应格式：

{
  "code": 0,
  "msg": null,
  "data": { ... }
}

• code: 0 表示成功，非 0 表示错误。
• 这是当前 Beta MVP 的响应格式，GA 版本可能迁移为 REST 资源模型。

---

API_CALL（积分类型）

通过 OpenAPI 调用图像处理接口时扣除的积分类型。与前端产品的 AI_IMAGE_TASK 积分类型相互独立，不相互影响。

---

频率限制（Rate Limit）

每个令牌每分钟可发起的最大请求次数。超出时返回 HTTP 429，需等待响应头 Retry-After 指定的秒数后重试。

---

终态（Terminal Status）

任务不再变化的最终状态。任务进入终态后应停止轮询。
当前终态：1（成功）、2（失败）、3（已取消）。

---

Bearer Token

HTTP 认证方案，令牌通过请求头携带：

Authorization: Bearer tsk_live_你的令牌

妙图设计 API 仅接受此格式，不支持 URL 参数或请求体传递令牌。