队列、限流与重试
H3 视频任务 API · /api/v3
排队与并发
| 规则 | 实际行为 |
|---|---|
| 并发 / 提交 RPM / 排队数 | 按客户账户＋模型统计，同账户的多个 Key 共享。 |
| 查询限流 | 查询 20 QPS、列表 1 QPS、取消 / 删除 20 QPS，分别按账户共享。 |
| 调度顺序 | 先账户公平轮转，再保护等待超过 300 秒的任务，之后按 priority 与创建先后分配；不抢断推理。 |
| 容量与队列 | 已验证规格先持久入队，卡忙或暂时离线时等待调度；不因预计等待较长拒绝。仅明确的账户提交频率、排队条数和平台安全上限会返回 429。 |
并发与排队上限由管理员配置；新账户默认可排队 200 条、每分钟提交 180 次。排队估算不承诺固定完成时间。多 Key 不能绕过账户限额。
安全重试
HTTP Header · 同一任务重试保持不变
Idempotency-Key: customer-video-20261102-001同账户、相同键与相同请求返回原任务，不重复受理；同键用于不同请求返回 409。新任务使用新键。
429 / 503 遵循 Retry-After，指数退避并加入抖动。查询失败只重试查询；创建超时仍用原幂等键重试，不直接新建第二个任务。
有效期与通知
| 时间 / 通知 | 说明 |
|---|---|
| 任务有效期 | 受理起含排队，默认 172800 秒，可设 3600～259200 秒，受平台上限约束。 |
| 视频链接 | 完成并可交付后固定 1 小时，查询不续期；过期的成功任务 URL 可能为 null。 |
| 任务记录 | 创建起 7 天，已取消任务保留 24 小时。 |
| HTTPS 回调 | callback_url 接收 queued、running 和终态快照；中间状态尝试一次，终态最多三次，2xx 视为成功。 |
回调可能重复或乱序，按任务 ID 和终态去重，以查询结果为准。接收端应先持久化事件并快速返回 2xx，再异步处理业务。平台不会要求在回调 URL 中携带 API Key。
接收任务完成回调
JSON · 创建任务时增加此字段
{
"callback_url": "https://YOUR_APP_HOST/webhooks/fablun"
}请求体结构与查询单个任务一致，成功时从 content.video_url 获取视频地址。回调超时为 5 秒，终态失败后间隔约 5 秒、15 秒重试，含首次最多 3 次；接收失败不取消生成，也不重新计费。
| 请求头 | 用途 |
|---|---|
| X-Fablun-Timestamp | 签名时间戳（秒） |
| X-Fablun-Signature | sha256= 加 HMAC-SHA256 十六进制签名 |
| X-Fablun-Event-ID | 稳定事件 ID，供接收端去重 |
验签内容为 timestamp + "." + 原始请求体，使用账户的回调签名密钥，采用恒定时间比较并校验时间戳（建议 5 分钟窗口）。密钥只供账户所有者读取；管理员重置密钥后需同步更新验签配置。旧版 X-Nabit-Timestamp、X-Nabit-Signature、X-Ravenzet-Event-ID 继续发送以兼容已有接入；新接入建议使用 X-Fablun 请求头。可在「我的组织 → 任务回调」查看签名密钥。