面向文本转视频团队的 Seedance API 生产清单

一个 Seedance API 原型在成功生成一条视频后，看起来就像已经完成了。但只有当你的系统能够承受慢任务、重复事件、不断变化的模型路由、部分失败以及不确定的成本时，生产集成才算真正完成。

这一差异很重要，因为视频生成并不是一个普通的请求-响应功能。应用会提交任务、等待、接收状态变化、保存一个较大的输出，并决定失败是否应该重试。模型调用只是更长工作流中的一个阶段。

这份清单会把该工作流转化为一个生产合同，供你的产品、平台和财务团队一起审阅。

当前路由说明： 在本指南检查于2026年7月27日，星期一时，Flatkey 的公开模型目录将 seedance-2.5 列为文本转视频和图像转视频模型，并将 seedance-2.0-i2v 列为图像转视频模型。请把这些名称视为目录状态，而不是永久常量。在发布或更改允许列表之前，请确认当前的 Flatkey 模型目录。

简短答案

不要把面向用户的请求直接连接到视频提供商调用。应在两者之间放置一个持久化的任务层。

你的最低生产路径应为：

1. 接收并验证用户的生成请求
2. 分配你自己的幂等键和任务 ID
3. 在调用模型路由之前先存储请求
4. 通过服务器端适配器提交任务
5. 以幂等方式处理 webhook 和轮询更新
6. 将完成的媒体复制到你可控的存储中
7. 记录延迟、失败原因、模型路由和预估成本
8. 暴露独立于提供商措辞的稳定产品状态

如果缺少其中任一步骤，集成可能仍然能很好地演示，但安全运维会更困难。

为什么 Seedance API 生产工作不同

文本生成通常在一次 HTTP 交互中返回有用结果。视频生成通常表现得更像一个分布式批处理任务。一次用户操作的生命周期可能会超出应用请求、部署、浏览器会话，甚至超出最终保存结果的临时 URL。

这些实际后果很容易被低估：

目标不是隐藏提供方，而是防止提供方特定行为变成你产品的永久契约。

1. 在载荷之前冻结产品契约

从你向用户承诺的体验开始，而不是从当前可用的提供方字段开始。

定义：

• 接受的输入类型：仅文本、图像加文本，或两者都支持
• 支持的宽高比和时长区间
• 最大上传大小和接受的媒体格式
• 提交前的审核和权利检查
• 预期的状态更新和取消行为
• 输出保留期
• 失败任务是否消耗用户点数
• 产品中的“重试”意味着什么

然后在适配器中将该契约转换为当前的 Seedance 路由。

这种分离可防止两种常见失败模式。第一，路由更新可能增加或重命名参数，而不会强制前端重写。第二，你的应用可以在为一个注定失败的任务花钱之前，先拒绝不受支持的组合。

2. 使用你自己的作业 ID 和幂等键

每个请求都需要两个标识符：

• 产品作业 ID：在你的系统中全程显示的稳定标识符
• 幂等键：用于防止意外重复提交的标识符

不要把提供方任务 ID 作为主键。它在提交后才会存在，而且如果你有意通过另一路由重新提交，它可能会变化。

一个简单的请求记录可以这样定义：

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

在发起外部 API 调用之前创建这条记录。如果应用在提交之后、保存响应之前崩溃，幂等键就能让你进行对账，而不是盲目地再次扣费生成。

3. 将 Seedance 放在一个服务端适配器后面

将供应商特定的请求构造集中在一个模块中。产品的其他部分应发送统一后的命令，例如：

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

适配器负责：

• 将 qualityProfile 解析为当前可用的模型和设置
• 在服务端附加身份验证
• 把你的画幅和时长选择转换为当前生效的 API schema
• 提交任务
• 统一供应商错误
• 存储供应商任务 ID
• 报告足够的元数据以便进行成本和可靠性分析

Flatkey 为团队提供一个 API key、一个稳定的路由端点、共享余额，以及跨模型家族的集中使用可见性。对于已经使用该访问层的团队，请将 Seedance 特有的异步逻辑保留在适配器中，而不是把路由假设散落到整个代码库。关于这个边界，之前的指南 Seedance API 团队稳定的 OpenAI 兼容 base URL 进行了更详细的说明。

4. 将工作流建模为状态机

不要让任意的状态字符串进入产品逻辑。要对它们进行归一化。

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

除非你正在运行明确的恢复流程，否则只允许向前转换。后到的 running 事件绝不能覆盖已标记为 succeeded 的任务。重复的 succeeded webhook 也绝不能触发两份存储副本或两次客户通知。

将原始的供应商事件单独存储以便调试，但产品决策应基于归一化后的状态。

5. 结合使用 webhooks 和轮询

Webhooks 很高效，但它们并不能保证你的应用会按顺序且只处理一次每个事件。轮询更慢，但对对账很有价值。

两者都要用：

• webhook 路径：低延迟状态更新
• 轮询路径：对最近没有变化的任务进行计划性恢复

你的 webhook 处理程序应当：

1. 当当前 API 支持验证时，对回调进行身份验证
2. 在不进行大量内联工作的情况下解析事件
3. 将事件指纹写入去重表
4. 入队处理
5. 快速返回成功

你的对账工作器应只轮询在合理延迟后仍处于非终态的任务。添加抖动，这样一次部署就不会在同一时刻触发成千上万次状态检查。

特定提供商的 webhook 和查询字段可能会发生变化。实施时应根据当前官方 API 参考进行核对，而不是从博客文章中复制旧的 payload。

6. 按故障类别决定是否重试

“重试失败任务”不是一项策略。它是一种成本风险。

将错误归一化为以下类别：

最后一个区分尤其重要。如果视频已成功生成，但你的存储复制失败，那么重新生成视频会带来不必要的成本，并且可能产生不同的结果。

为每个任务设置重试预算。合理的策略可能会允许比生成提交更多的状态检查和存储复制尝试。

7. 将输出复制到你可控的存储中

应将任何提供商托管的结果 URL 视为传输位置，而不是你永久的产品资产。

任务成功后：

1. 验证响应是否包含预期的媒体类型
2. 在大小和时间限制内下载
3. 验证文件不是空的，也没有明显被截断
4. 计算校验和
5. 将其复制到你的对象存储
6. 保存时长、尺寸、编解码器和大小
7. 仅在持久副本可用后，将产品任务切换为 succeeded

如果你的产品允许用户在复制完成前下载原始提供商资产，请将其表示为单独的临时状态。不要在不提示的情况下承诺永久可用。

8. 在开放功能前加入成本控制

视频任务的成本足够高，因此在公开发布之前就应设置产品限制。

至少应定义：

• 按密钥或按团队的支出上限
• 应用密钥的模型白名单
• 每个账户的最大并发任务数
• 按套餐设置的最大时长和质量配置
• 针对新账户或不受信任账户的每日提交限制
• 当失败率或每次成功成本上升时的熔断机制

Flatkey 的公开文档描述了按密钥上限、可选模型白名单，以及通过 Usage & Logs 或 ledger API 进行使用情况可见性。将这些控制用作访问层的防护栏，然后根据你自己的套餐和滥用风险添加产品级配额。

在启用新路由之前，请对比当前目录和 Flatkey pricing。不要在应用逻辑中嵌入本文中的数字价格；价格和路由可用性都是可刷新数据。

9. 衡量整个任务，而不只是 API 延迟

对于异步的 Seedance API 工作流，成功提交仍然可能带来糟糕的客户体验。

至少跟踪以下指标：

• 提交接受率
• 队列等待时间
• 生成时间
• 到持久化输出的总耗时
• 按已解析模型统计的成功率
• 按标准化失败类别统计的失败率
• webhook 投递延迟
• 轮询恢复率
• 存储复制失败率
• 每个已提交任务的成本
• 每个成功持久化输出的成本
• 重复提交防止次数

使用百分位数，而不只是平均值。中位生成时间看起来可能很健康，而最慢的 10% 任务却会产生大多数支持工单。

同时分别记录 requestedModel 和 resolvedModel。这样可以让路由变更可见，并为回滚决策提供证据。

10. 将模型变更作为迁移发布

目录变更不只是字符串替换。应将其视为一次依赖升级。

在将生产流量迁移到新的 Seedance 路由之前：

1. 在在线模型目录中确认当前路由
2. 对比支持的输入和输出约束
3. 针对常见提示词类型运行固定评估集
4. 对比成功率、延迟、输出接受率和成本
5. 测试 webhook、轮询和错误标准化
6. 对一小部分流量进行金丝雀发布
7. 在金丝雀稳定之前保留回滚路由
8. 更新模型白名单和运维手册

如果你的应用提供“质量”设置，请将其映射到能力配置文件，而不是永久性的模型 ID。这样你就可以在不破坏产品 API 的情况下更换底层路由。

生产就绪检查清单

将此列表用作上线门槛。

请求与访问

• [ ] API 密钥仍保留在服务器端
• [ ] 应用密钥具有支出上限和模型白名单
• [ ] 每个请求都有内部任务 ID 和幂等键
• [ ] 在提交前已验证输入
• [ ] 已在在线目录中检查当前 Seedance 模型路由

异步执行

• [ ] 提供商特定逻辑集中在一个适配器中
• [ ] 产品状态使用标准化状态机
• [ ] 在支持的情况下对 webhook 事件进行认证并去重
• [ ] 轮询机制可重新同步陈旧的非终态任务
• [ ] 迟到或重复事件不能回滚终态

可靠性与成本

• [ ] 重试行为会根据失败类别而变化
• [ ] 生成重试有严格预算
• [ ] 输出复制重试不会重新生成成功的视频
• [ ] 并发和每日任务限制已强制执行
• [ ] 熔断器可暂停降级路由

输出与可观测性

• [ ] 成功的媒体已复制到受控存储中
• [ ] 输出元数据和校验和已存储
• [ ] 已记录请求的模型 ID 和解析后的模型 ID
• [ ] 已衡量每个成功的持久化输出的成本
• [ ] 运维人员拥有用于处理卡住、失败和重复作业的运行手册

Flatkey 的适用位置

Flatkey 并不会消除对异步视频作业层的需求。它减少了围绕该层的访问和治理工作：一个账户、一个余额、API 密钥控制、稳定的路由器表面、实时模型目录，以及集中化的使用记录。

对于首次集成，请从更全面的 面向文本转视频产品团队的 Seedance API 快速入门 开始。当功能推进到生产阶段时，请将此清单应用到模型调用周围的队列、状态、重试、存储和可观测性层。

如果你的团队正在决定哪条当前路由和使用控制适合此次上线，请在批准生产配置之前查看 实时模型 和 定价。

常见问题

Seedance API 是同步还是异步？

应将视频生成视为异步作业。你的产品应提交工作、返回自己的作业 ID，并根据当前 API 参考通过 webhook 和/或轮询处理状态更新。

我应该使用提供方的任务 ID 作为数据库主键吗？

不应该。请在提交前创建你自己的稳定作业 ID。将提供方任务 ID 作为外部引用存储，以便你在不更改产品标识符的情况下进行对账、重新提交或更换路由。

我需要同时使用 webhook 和轮询吗？

对于一个健壮的生产系统，是的。webhook 提供快速更新；轮询可恢复事件延迟、遗漏或未处理的作业。

失败的 Seedance 作业什么时候可以安全重试？

只有在对失败进行分类之后才重试。容量和网络故障可能可以重试。验证、认证、安全或其他终态失败通常需要配置变更或用户变更。如果提交超时，请在发送另一个付费作业之前，先通过幂等键进行对账。

我应该自己存储生成的视频吗？

应该。将已完成的输出复制到你可控制的存储中，验证文件，并保存其元数据。除非当前条款明确保证这种行为，否则不应将提供方托管的结果 URL 视为永久的产品存储。

我应该如何处理新的 Seedance 模型版本？

将其视为一次迁移：验证当前目录，运行固定的评估集，对比质量、延迟、失败率和成本，进行金丝雀流量发布，并在变更稳定之前保留回滚路径。

我应该硬编码哪一个 Seedance 模型？

避免基于静态文章永久硬编码某个模型。应将产品能力配置文件解析为当前 Flatkey 模型目录中列出的模型，并将选定的路由保存在配置中，以便运维人员可以安全地更改它。