积分与限速

积分概述

妙图设计 API 使用**积分（Point）**作为计费单位。每次调用图像处理接口时，从账户余额中扣除对应积分。

API 积分与前端积分的区别

类型	触发方式	积分类型	说明
API 调用积分	通过 OpenAPI 调用	API_CALL	本文档所描述的计费
前端图像积分	通过妙图产品前端操作	AI_IMAGE_TASK	产品内部计费，与 API 独立

两者相互独立：通过 API 消耗积分不影响前端配额，通过前端操作消耗积分不影响 API 额度。

---

余额查询

通过 GET /account/balance 查看当前积分状态：

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

响应字段说明：

{
  "code": 0,
  "msg": null,
  "data": {
    "balance": 850,
    "reserved": 10,
    "available": 840,
    "expiringIn7Days": 50,
    "nextExpireAt": 1749340800000
  }
}

字段	说明
balance	账户总积分
reserved	处理中任务已预占的积分
available	可用积分（balance - reserved）
expiringIn7Days	7 天内将到期的积分数量
nextExpireAt	最近一批积分的到期时间（Unix 毫秒时间戳，null 表示无即将到期的积分）

积分到期为批次到期，非全局过期。expiringIn7Days 仅计算最近 7 天内到期的批次总量。

---

余额不足（402）

当账户可用积分不足以支付本次调用时，接口返回 HTTP 402：

{
  "code": 1004008000,
  "msg": "用户积分余额不足",
  "data": null
}

处理方式：

1. 调用 GET /account/balance 确认余额。
2. 在妙图产品内充值积分。
3. 余额补充后重新发起请求。

---

月度积分上限（402）

每个令牌可以设置月度积分上限，防止单令牌在一个月内超支。超出上限时返回 HTTP 402：

{
  "code": 1004013001,
  "msg": "API Token 月度积分上限已超过",
  "data": null
}

处理方式：

1. 在 账户 → API 密钥 页面调高该令牌的月度上限。
2. 或等待下个自然月重置后继续使用。
3. 注意：月度上限是令牌级别的限制，不影响账户总余额。

---

频率限制（429）

每个令牌有每分钟调用次数上限（Rate Limit）。超出后返回 HTTP 429：

{
  "code": 429,
  "msg": "Too Many Requests",
  "data": null
}

响应头中包含等待时间：

Retry-After: 30

正确的重试策略：

# 伪代码
while true:
  response = call_api(...)
  if response.status == 429:
    wait_seconds = response.headers["Retry-After"] or 60
    sleep(wait_seconds)
    continue
  break

注意：

• 不要忽略 429 直接重试，否则会持续触发限制。
• 读取 Retry-After 头中的秒数并等待后再重试。
• 若频率限制对业务有影响，请联系支持团队评估提额。

---

推荐的客户端错误处理策略

HTTP 状态	处理建议
402 (余额不足)	停止重试，提示用户充值后再操作
402 (月度上限)	停止重试，提示用户调整令牌上限
429 (频率限制)	等待 Retry-After 秒后重试，最多重试 3 次
5xx (服务端错误)	使用指数退避策略重试，最多重试 3 次
401 / 403	不要重试，检查令牌配置