百度一镜数字人API返回429错误是因瞬时QPS或并发超限，需通过控制台查配额、加随机延迟、令牌桶限流、合并请求、按Retry-After重试及升级API Key解决。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
调用百度一镜数字人API时频繁收到429错误，说明当前请求节奏已突破服务端设定的速率窗口，必须立即调整客户端行为才能恢复调用。该接口对QPS（每秒请求数）和并发连接数实施双重硬限，且不支持跨账户额度共享。
确认当前API Key的实际配额
登录百度千帆控制台 → 进入“我的应用” → 选择对应一镜数字人应用 → 点击“API Key管理” → 查看右侧“配额详情”面板中显示的QPS与并发上限值。免费版默认为【3 QPS & 2并发】，企业版需手动开通并审批后生效。
注意：控制台显示的“日调用量”不限制实时频率，仅统计总量；真正触发429的是瞬时QPS或并发数超限，与当日剩余调用量无关。
降低客户端请求密度
方法一：强制插入随机延迟
在每次请求发起前，调用系统时间生成100–300毫秒随机休眠。Python示例：time.sleep(random.uniform(0.1, 0.3))。这能打散周期性请求峰，避免整秒时刻集中撞限。
方法二：启用令牌桶本地限流
使用ratelimit库封装请求函数，初始化桶容量=3、填充速率=3/秒。每次调用前尝试获取令牌，失败则阻塞等待。此方式比简单sleep更精准，且能应对突发流量。
调用百度文档解析API，支持18+格式，提取文本、表格、版面分析、OCR识别及RAG文档分块。适用于文档解析、文本/表格提取、结构分析、扫描件处理。触发词：文档解析、PDF解析、Word解析、表格提取、OCR、文档分析、提取文本、文档结构、扫描识别。
方法三：合并请求体减少调用次数
一镜数字人支持单次提交多段文本生成多个数字人动作帧。将原本分散的5次单句合成请求，改为1次含5个text字段的批量请求，可降低80%调用频次。但需注意单请求总字符数不能超过8192，否则会返回400错误。
处理429响应并自动重试
第一步：捕获HTTP状态码为429的响应
所有HTTP客户端（如requests、axios）都必须显式判断response.status_code == 429，不能仅靠异常机制。
第二步：读取响应头Retry-After字段
百度一镜数字人API在返回429时，必定携带Retry-After: 1（单位为秒）。直接提取该值作为暂停时长，比固定退避更可靠。
第三步：执行指数退避重试
若响应头无Retry-After字段，则启用基础退避：首次等待1秒，第二次2秒，第三次4秒。最大重试次数设为【3次】，超过即抛出原始错误，防止雪崩。
升级API Key配额
进入千帆控制台“API Key管理”页面 → 找到目标Key → 点击“编辑” → 在弹窗中选择“升级为专业版” → 提交工单并等待审核。审核通过后配额即时生效，无需重启服务或更换Key。
