参考

配额与限流

Embedded 各接口的限流维度、限流响应契约与客户端重试策略;内测期具体阈值以联调口径为准。

配额与限流处于内测阶段,各维度的具体阈值不在本页给出,一律以联调时对接工程师提供的口径为准。接入请见联系我们。

限流维度

限流以 client_id 为主体计量。当前生效的限流维度如下,阈值在联调时按你的业务规模逐项确认。

限流维度	说明	内测期取值
API QPS	单个 `client_id` 每秒可发起的 API 请求数,覆盖认证、文件上传与转写全部接口。	以联调口径为准
并发转写任务数	同一 `client_id` 下同时处于进行中状态(`PENDING` / `RECEIVED` / `STARTED` / `PROGRESS`)的转写任务数量上限。	以联调口径为准
令牌签发频率	合作方令牌与用户令牌的签发、续期接口的调用频率。令牌应在有效期内缓存复用,不应在每次业务请求前重新签发。	以联调口径为准
上传并发连接	分片上传时,单个客户端可同时打开的上传连接数。分片并发度应控制在该上限内。	以联调口径为准

免费额度

限流与用量额度是两件事:限流约束请求的速率,用量额度约束累计消耗。新接入的 Embedded 开发者拥有 50 台设备连接 + 300 小时转写的免费额度,超出后走按量付费。完整口径见计费。

限流响应契约

触发限流时,接口返回 HTTP 429,并携带 Retry-After 响应头(单位为秒),指示至少等待多久后再重试。响应体为统一错误结构,字段口径见错误码。

429 限流响应示例

HTTP/1.1 429 Too Many Requests
Retry-After: 3
Content-Type: application/json

{
  "code": "IKHO_ERR_RATE_LIMITED",
  "message": "请求频率超出当前配额,请稍后重试。",
  "request_id": "req_7f2e9c"
}

以上为内测契约,错误结构与 Retry-After 的具体行为以联调时提供的正式文档为准。排查问题时请保留 request_id,便于对接工程师定位。

重试策略最佳实践

客户端遇到 429 或 5xx 时,建议按以下顺序决定等待时间:

响应带 Retry-After 时,优先遵守服务端下发的等待时间;
否则按指数退避计算等待时间,并叠加随机抖动,避免多个客户端在同一时刻集中重试;
设置重试次数上限,用尽后把最后一次响应交给业务层处理,不要无限重试。

JavaScript · 指数退避 + 抖动

const MAX_RETRIES = 5;
const BASE_DELAY_MS = 1000;
const MAX_DELAY_MS = 30000;

function sleep(ms) {
  return new Promise(function (resolve) { setTimeout(resolve, ms); });
}

async function requestWithRetry(url, options) {
  let resp;
  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
    resp = await fetch(url, options);

    // 非限流、非服务端错误:直接返回,交给业务层处理
    if (resp.status !== 429 && resp.status < 500) {
      return resp;
    }
    if (attempt === MAX_RETRIES) {
      break; // 重试次数用尽,把最后一次响应交给上层
    }

    // 优先遵守服务端下发的 Retry-After(秒)
    const retryAfter = Number(resp.headers.get('Retry-After'));
    let delay;
    if (Number.isFinite(retryAfter) && retryAfter > 0) {
      delay = retryAfter * 1000;
    } else {
      // 指数退避:1s、2s、4s,封顶 30s
      delay = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
    }
    // 全抖动:在 [0, delay] 区间取随机值
    await sleep(Math.random() * delay);
  }
  return resp;
}

幂等性提示

提交音频转写接口不做服务端去重:同一段音频重复提交会创建多个转写任务,分别计入并发任务数与转写小时数。对提交类请求重试前,请先确认上一次请求是否已成功创建任务(例如记录已返回的 transcription_id,或在业务侧维护自己的幂等键),避免重复任务带来的额度消耗。

需要更高额度怎么办

内测期的限流阈值面向联调与小范围试点。如果你的业务需要更高的 QPS、更多并发转写任务或更大的用量额度,可以走企业方案,按业务规模单独约定阈值与结算方式。请通过联系我们与团队沟通。

这一页有帮助吗?