基于 EvoLink 的 Seedance 1.5 Pro API 集成指南：异步任务、回调与模式详解

你将学到什么

• 通过 EvoLink 的异步任务 API（创建 → 状态查询 → 获取结果）集成 Seedance 1.5 Pro。
• 安全地使用 callback_url（仅限 HTTPS、重试机制及失败处理）。
• 如何使用单一端点实现 文字生成视频 (Text-to-Video)、图片生成视频 (Image-to-Video) 以及 首尾帧生成 (First-Last-Frame)。
• 使用幂等键 (Idempotency Key) 和重试预算防止重复处理。
• 在资源链接过期前（24小时保留期）重新转存输出资源。
• 在不依赖不可靠的定价快照的情况下，构建“单次成功输出成本”模型。
• 对比 Veo 3.1 和 Kling O1 的集成权衡（基于架构设计而非单纯价格）。

快速入门检查清单（可直接复制到你的任务卡片中）

• 实现 POST /v1/videos/generations 以创建任务
• 实现 GET /v1/tasks/{task_id} 轮询机制
• 实现 callback_url 端点（2xx 快速响应 + 异步处理）
• 针对每个用户意图（如点击“生成”按钮）添加幂等键
• 在 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 张图片 → 文生视频 (Text-to-Video)
• 1 张图片 → 图生视频 (Image-to-Video)
• 2 张图片 → 首尾帧模式 (基于首帧和末帧的引导生成)

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

生产环境中需要关注的请求字段

以下是你实际开发中需要操作的参数：

• model: 使用 "seedance-1.5-pro"
• prompt (必填): 最多 2000 个 token
• duration: 默认为 5s；支持 4–12s

  架构注意：计费随时长线性缩放，应将时长作为核心成本杠杆。

• 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 → (下载 → 转存 → 交付给用户)
                     └──────→ failed (策略拒接 | 瞬时错误 | 内部错误)
                     └──────→ cancelled

最小可用示例 (EvoLink)

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

本示例采用无特殊符号的 Prompt，避免 Shell 转义问题。

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <您的令牌>' \
  --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 <您的令牌>'

任务完成后，返回体将包含：

• 带有输出 URL 的 results 数组
• status 和 progress 进度

callback_url：可靠性准则（严禁忽略）

• 仅限 HTTPS
• 禁止使用内部/私有网络 IP
• 超时时间：10 秒
• 最多重试 3 次，间隔分别为 1 / 2 / 4 秒
• 回调体格式与查询任务接口的返回格式一致

回调生产环境检查清单

• 在 200ms–500ms 内响应 2xx（仅入队处理，不要在同步流程中执行耗时操作）
• 验证 task_id 确实存在且属于该用户
• 在标记最终状态前，再次手动调用 GET /v1/tasks/{task_id} 进行校验
• 回调去重逻辑（存储 task_id + 终态，忽略重复请求）
• 记录原始回调报文用于调试（隐藏敏感信息）
• 监控回调失败率（一旦升高通常意味着你的端点出了问题）

幂等性：防止重复处理（及“付两份钱”现象）

即便是稳定的平台，由于以下原因你的系统仍可能产生重复：

• 用户连续点击“生成”按钮
• 移动网络超时后的自动重试
• 网关超时

• 客户端根据用户意图生成 idempotency_key（一次点击 = 一个 Key）
• 服务端存储 (user_id, idempotency_key) → task_id 的映射（带 TTL）
• 对于重复请求，直接返回同一个 task_id 而不是创建新任务

不要假设接口会“自动帮你处理”幂等逻辑，除非文档明确说明。请在应用边缘层实现。

资源交付：24 小时“陷阱”

由于输出链接会在 24 小时后过期，你的流水线应当：

• 在 status=completed 时立即下载结果
• 重新上传到你自己的对象存储（S3/GCS/R2）
• 通过 CDN 提供访问
• 持久化元数据：task_id、Prompt 哈希、用户 ID、时长、画质、音频标志、分级过滤结果

通过在完成时自动转存来彻底消除此风险。

灵活的成本建模（非固定单价）

即使定价可能会变动，你依然可以建立一套耐用的单位经济模型。

1) 明确计费影响因素

从运营层面看，你的支出取决于：

• duration 时长（片段越长，费用越高）
• generate_audio（音频会产生额外费用）
• 迭代次数（用户很少能在第一次尝试就获得满意的结果）

2) 统计“单次成功输出成本”，而非“单次尝试成本”

跟踪以下指标：

• attempts_per_success（单次成功所需的平均尝试次数）
• retry_rate（重试率）
• policy_failure_rate（违反策略导致的失败率）
• p95_latency（延迟分布）

真实的单位经济：

单个会话成功输出数 × 达成成功所需的平均尝试次数

3) 预览 → 审核 → 确认终版（最高效的降本策略）

针对高频迭代用户：

• 先用低画质/短时长或更便宜的模型生成预览
• 用户选定后，再启用 Seedance 1.5 Pro（带音频）生成最终版

不承诺固定的折扣比例，通过可预测的迭代策略应对消耗。

生产环境坑位及对策

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

• 设置任务有效时长 (TTL) 并在前端展示“处理中”状态
• 监控 p95 完成时间；当延迟激增时提供降级方案

2) 内容分级审核结果可能延迟

设计好对应的 UI/后端状态，处理“生成完后检测失败”的情况。

• 区分：策略截断 vs 瞬时错误 vs 内部错误
• 绝对不要对违反内容的请求进行自动重试
• 提供 Prompt 重写指引（特别是针对敏感词内容的引导）

对比：Seedance 1.5 Pro vs Veo 3.1 vs Kling O1（无价格快照版）

单纯的数字很快会过时。我们应该对比那些长久的能力设计和工作流适配。

表 A — 集成与成本核算设计

表 B — 生产决策矩阵

决策清单（快速判断）

• 你需要原生音轨，并能通过引号结构优化台词效果。
• 虽然业务涉及文生视频、图生视频和首末帧切换，但希望合约统一。
• 你的架构能够支持在 24 小时内完成资源转存。

• 你更偏好以时长为核心的预算管理方式，且深耕相关的云生态工作流。

• 编辑和重绘是你的核心卖点，且你已确认了稳定的接入路径。

常见问题解答 (FAQ)

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

Q: 回调还是轮询更安全？

Q: 为什么必须转存结果？

因为链接会在 24 小时后失效。请务必及时下载并存入自己的存储空间。

Q: 如何制定单位经济模型？

关注单次成功输出的成本，而非单次尝试。统计平均尝试次数、重试率及策略拦截率。

Q: 如何避免用户重复操作产生重复任务？

立即开始使用 Seedance 1.5 Pro

你已经了解了合约逻辑和各种权衡。 现在，将其转化为你的生产力功能吧。

• 一个 API Key 即可访问 Seedance 1.5 Pro, Veo 3.1, Kling 等多种模型。
• 异步任务 + 回调机制，具备明确的重试语义。
• 按需计费，额度透明，无最低消费门槛。

大多数团队在不到一小时内即可完成集成。