Seedance 1.5 Pro API 集成指南：异步任务、回调与模式切换

本指南聚焦实战：你真正要上线的接口契约、会遇到的故障模式，以及避免重复扣费或丢失产出的运维模式。

你将学到

• 通过 EvoLink 异步任务 API 接入 Seedance 1.5 Pro（创建 → 查询 → 获取结果）
• 安全使用 callback_url（仅 HTTPS、重试语义、失败处理）
• 用同一个端点实现文生视频、图生视频和首尾帧控制
• 通过幂等键和重试预算防止重复处理
• 在链接过期前完成资源托管（24 小时有效期）
• 建立「单次成功产出成本」模型，而非依赖易变的价格快照
• 对比 Veo 3.1 和 Kling O1 的集成差异（基于架构，而非价格）

快速上手清单（可直接复制到工单）

• 实现 POST /v1/videos/generations 创建任务
• 实现 GET /v1/tasks/{task_id} 轮询
• 实现 callback_url 回调端点（快速返回 2xx + 异步处理）
• 为每次用户意图添加幂等键（一次点击 = 一个 key）
• 24 小时内完成视频资源托管
• 埋点监控：p50/p95 延迟、策略失败率、重试率、成功产出所需尝试次数

EvoLink API 契约：你真正要上线的接口

• 创建任务 → 获得 task_id
• 轮询 GET /v1/tasks/{task_id} 或通过 callback_url 接收回调
• 任务完成后获取 results URL，立即下载（链接会过期）

端点概览

• POST https://api.evolink.ai/v1/videos/generations

• GET https://api.evolink.ai/v1/tasks/{task_id}

• 产出链接 24 小时内有效，请及时托管。

一个端点，三种模式（通过 image_urls 自动检测）

• 0 张图片 → 文生视频
• 1 张图片 → 图生视频
• 2 张图片 → 首尾帧控制（首帧 + 尾帧引导）

• 每次请求最多 2 张图片
• 单张图片 ≤ 10MB
• 支持格式：jpg/jpeg/png/webp
• URL 必须可被服务器直接访问

生产环境中真正重要的请求参数

以下是你实际运维时会关注的参数：

• model：使用 "seedance-1.5-pro"
• prompt（必填）：最多 2000 tokens
• duration：默认 5 秒，支持 4–12 秒

  运维提示：计费随时长增加，把 duration 当作一级成本杠杆。

• quality：480p 或 720p（默认 720p）
• aspect_ratio：16:9、9:16、1:1、4:3、3:4、21:9、adaptive（默认 16:9）
• generate_audio：布尔值（默认 true）

  技巧：将对话内容放在英文双引号内，可提升语音生成效果。

• callback_url：任务完成/失败/取消时的 HTTPS 回调地址（推荐使用）

场景化参数推荐（快速决策）

此表可直接引用到文档或 PRD 中。

任务生命周期：先设计状态机

可靠的集成始于可预测的内部状态机：

created → queued/processing → succeeded → (download → rehost → delivered)
                     └──────→ failed (policy | transient | internal)
                     └──────→ cancelled

最小可用示例（EvoLink）

1) 创建任务（cURL）——可直接复制

此示例避免了 shell 转义问题，prompt 中不含撇号。

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-1.5-pro",
    "prompt": "A detective in the rain says: \"Do not move.\" Neon reflections on the street. Subtle footsteps and radio static.",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "callback_url": "https://your-domain.com/webhooks/evolink-task"
  }'

API 立即返回任务对象，至少包含：

• id（任务 ID）
• status
• usage 字段（如 billing_rule、credits_reserved）

2) 轮询任务状态（cURL）

curl --request GET \
  --url https://api.evolink.ai/v1/tasks/<task_id> \
  --header 'Authorization: Bearer <token>'

任务完成后，响应包含：

• results 数组（含产出 URL）
• status 和 progress

callback_url：可靠性规则（不可跳过）

• 仅支持 HTTPS
• 内网/私有 IP 被屏蔽
• 超时：10 秒
• 最多重试 3 次，退避间隔 1 / 2 / 4 秒
• 回调体格式与任务查询 API 响应一致

回调生产检查清单（可直接复制）

• 200ms–500ms 内返回 2xx（重活异步处理，不要阻塞）
• 校验 task_id 存在且属于当前租户/用户
• 在最终确认状态前，立即重新查询 GET /v1/tasks/{task_id}
• 回调去重（存储 task_id + 最终状态，忽略重复）
• 记录原始回调 payload 用于调试（脱敏处理）
• 回调失败率上升时告警（通常说明你的端点有问题）

幂等性：防止重复处理（和「扣两次费」）

即使服务商没问题，你的系统仍可能产生重复任务，因为：

• 用户双击「生成」按钮
• 移动网络自动重试
• 网关超时

• 客户端为每次用户意图生成 idempotency_key（一次点击 = 一个 key）
• 服务端存储 (user_id, idempotency_key) → task_id，设置 TTL
• 重复请求时返回相同的 task_id，而非创建新任务

除非 API 文档明确说明支持幂等，否则不要假设「已经帮你处理了」。在应用边界自己实现。

资源交付：24 小时陷阱

产出链接 24 小时后过期，你的流程应该：

• 任务 status=completed 后立即下载
• 托管到自有对象存储（S3/GCS/R2）
• 通过 CDN 分发
• 持久化元数据：task_id、prompt 哈希、用户 ID、duration、quality、audio 标记、审核结果分类

解决方案：任务完成后自动托管。

成本建模：不依赖价格快照也能落地

即使你不公开定价，仍需要一个可持续的单位经济模型。

1) 了解平台的计费维度

运营层面，你的支出由以下因素驱动：

• duration（时长越长越贵）
• generate_audio（开启音频增加成本）
• 迭代次数（用户很少一次就满意）

2) 按「单次成功产出成本」预算，而非「单次尝试成本」

追踪：

• attempts_per_success（按场景）
• retry_rate
• policy_failure_rate
• p95_latency

你的真实单位成本：

每会话成功产出数 × 平均所需尝试次数

3) 草稿 → 确认 → 定稿（最可靠的降本模式）

当迭代频繁时：

• 草稿阶段用低配参数（如低画质/短时长）或更便宜的模型
• 用户确认后再用 Seedance 1.5 Pro（带音频）生成定稿

不承诺固定百分比——但这是一个随迭代率提升而收益递增的可预测策略。

生产环境常见坑与解法

1) 异步陷阱（超时 + 僵尸任务）

• 设置「任务 TTL」和「处理中」UI 状态
• 监控 p95 完成时间，异常时优雅降级

2) 审核结果可能延迟到达

为「处理后失败」设计 UI 和后端状态。

• 区分：策略失败 vs 瞬时失败 vs 内部错误
• 策略失败不要自动重试
• 提供 prompt 改写建议（尤其是敏感内容）

3) 存储是 API 的一部分

二进制文件很重：

• 不要让流量穿透网关
• 下载 → 存储 → CDN

横向对比：Seedance 1.5 Pro vs Veo 3.1 vs Kling O1（不含价格快照）

价格会变，架构不会。本节聚焦：计费模型、集成契约和工作流适配。

表 A — 集成与计费架构

表 B — 生产决策矩阵

决策清单（快速判断）

• 你需要原生音频，且能用引号结构化对话
• 你需要文生视频 + 图生视频 + 首尾帧控制在同一契约下
• 你能在 24 小时内完成资源托管

• 你偏好按时长预算，且已在 Google 云生态内

• 编辑/风格化是产品核心，且你已确认接入语义稳定

常见问题

Q: 如何在 EvoLink 上切换文生视频和图生视频？

Q: Webhook 还是轮询——哪个更安全？

Q: 为什么必须托管产出资源？

链接 24 小时后过期。请及时下载并存储。

Q: 单位经济的正确计量单位是什么？

单次成功产出成本，而非单次尝试成本。追踪成功所需尝试次数、重试率和策略失败率。

Q: 如何避免用户重试时产生重复任务？

立即开始集成 Seedance 1.5 Pro

你已经了解了接口契约，也清楚了各种权衡。 现在，把它变成生产级功能。

• 一个 API Key 接入 Seedance 1.5 Pro、Veo 3.1、Kling 等模型
• 异步任务 + 回调 带明确的重试语义
• 按量计费 透明积分，无最低消费

大多数团队在一小时内完成集成。