Ideal House
跳转到主要内容

API 任务限制#

生成类 API 采用异步任务处理机制。任务成功创建后，API 将返回一个 taskId。请使用结果端点来查询任务状态、进度、队列位置和最终输出。

本文档说明了 API 集成的公开任务限制，包括每分钟请求数、未完成任务数，以及在提交多个任务时的积分扣费方式。

速率限制概览#

生成类 API 对任务创建没有固定的公开 每分钟请求数 限制。实际限制取决于账户在同一时间有多少个未完成的任务。

工作流每分钟请求数并发 / 未完成任务积分扣费
AI 3D无固定公开 RPM 限制同时仅 1 个运行任务。额外提交的任务将在队列中等待。按接受的任务计费
其他生成类 API无固定公开 RPM 限制每个账户和工作流最多 30 个未完成任务按接受的任务计费

未完成任务包括队列中的任务和运行中的任务。

30 任务限制是任务数量限制，而非积分套餐或免费额度。每个接受的生成任务均按该 API 的积分规则计费。

任务状态#

状态含义是否计入未完成
Unprocessed任务已被接受，正在等待运行是
Processing任务正在运行中是
Success任务已成功完成否
Failed任务失败否

结果端点还可能返回 waitNumber，表示等待任务的队列位置。当任务正在运行或已完成时，waitNumber 通常为 0。

AI 3D 任务#

AI 3D 任务一次只处理一个。

您可以提交多个 AI 3D 任务，每次成功提交都会返回一个 taskId。然而，同一时间只能有一个 AI 3D 任务运行。额外的 AI 3D 任务将等待当前任务完成后才开始执行。

推荐的集成行为：

  1. 保存返回的 taskId。
  2. 每 3-5 秒 轮询一次结果端点。
  3. 将 Unprocessed 视为等待中。
  4. 将 Processing 视为正在运行。
  5. 使用 waitNumber 和 percentage 向用户展示进度。

其他生成类任务#

对于 AI 3D 以外的工作流，每个账户的同一工作流最多可以有 30 个未完成任务。

这是账户级别的限制。如果在同一账户下创建了多个 API 密钥，它们共享同一限制。

这并不意味着所有 30 个任务都在同一时刻真正运行。有些任务可能在等待，有些可能在运行，但限制对两者都计数。

当账户对于某个工作流已有 30 个未完成任务时，针对该工作流的新任务提交可能会被暂时拒绝，直到现有任务完成。

代码名称含义
9015TASK_NOT_COMPLETED账户已达到该工作流的未完成任务上限。待现有任务完成后重试。

积分与未完成任务#

积分在生成任务成功创建时扣除。如果任务最终失败，扣除的积分将自动退还。

未完成任务限制不会影响每个任务的积分成本。如果您提交多个任务，每个被接受的任务都会分别计费。

示例：

示例活跃未完成任务数任务创建时扣除的积分
提交 30 个更换家具任务3030 x 1 积分 = 30 积分
提交 30 个家居装饰任务（使用 modelType: "Base"）3030 x 3 积分 = 90 积分
提交 30 个家居装饰任务（使用 modelType: "Pro"）3030 x 10 积分 = 300 积分
提交 10 个园林美化 Flash 任务、10 个 Base 任务和 10 个 Pro 任务3010 x 1 + 10 x 3 + 10 x 10 = 140 积分

完整积分表请参阅 积分扣除参考。

轮询结果端点不会创建新的生成任务，也不计入未完成任务数。

临时服务繁忙响应#

在某些情况下，由于服务繁忙，新任务提交可能会被暂时拒绝。即使您的账户未完成任务数少于 30 个，也可能发生这种情况。

代码名称含义
5020QUEUE_TASK_OVERFLOW服务当前繁忙。请稍后重试。

这是临时性的，请不要将其视为永久失败。

推荐的客户端行为#

  1. 保存每次返回的 taskId。
  2. 定期轮询任务状态。
  3. 维护每个账户和工作流的未完成任务本地列表。
  4. 当任务状态变为 Success 或 Failed 时，将其从未完成列表中移除。
  5. 对于非 AI-3D 工作流，在提交更多任务前，确保未完成任务数保持在 30 或以下。
  6. 如果收到 9015 或 5020，请延迟后重试。

建议的重试行为：

情况建议操作
9015 TASK_NOT_COMPLETED等待同一账户和工作流的现有任务完成，然后重试。
5020 QUEUE_TASK_OVERFLOW等待并使用退避策略重试。
任务处于 Unprocessed 状态继续轮询；任务正在等待。
任务处于 Processing 状态继续轮询；任务正在运行。

需要更高的吞吐量？#

如果标准的 每账户每工作流 30 个未完成任务 限制无法满足您的集成需求，请通过 [email protected] 联系我们。我们可以评估您的使用场景，并讨论提高吞吐量或专用方案的选项。