dsh-seedance2：DeepSeek Harness 上的 Seedance 2 图像与视频生成

前言¶

在 DeepSeek Harness (DSH) 的开发中，当智能体需要生成图像或视频时，通常需要自行封装 HTTP 调用逻辑。dsh-seedance2 是一个插件，通过 Seedance 2 AI 公共 API，将图像和视频生成能力直接集成到 Harness 中。该插件由 SynMind AI 维护，支持通过 Seedance 2 或 2.5 模型进行生成。

安装与启用¶

安装插件需要使用 DSH 的插件管理命令。安装完成后，需要检查配置转储以确认插件已生效。

npx -y @deepseek-ai/dsh plugin --profile web add dsh-seedance2
npx -y @deepseek-ai/dsh --profile web --dump-config
npx -y @deepseek-ai/dsh web --profile web

上述命令会将 seedance2 配置层添加到 Harness 中。如果需要从本地代码仓库安装，可以使用：

npx -y @deepseek-ai/dsh plugin --profile web add .

配置与认证¶

插件通过 Harness 的凭证系统解析 API 密钥，该密钥不会作为模型参数直接暴露在 Prompt 中。

在 Seedance 2 官网注册或登录，并购买积分。
在 API 管理页面创建 API Key。
在启动 Harness 的环境中设置环境变量：

export SEEDANCE2_PUBLIC_API_KEY='sk-...'

重启 Harness。

核心功能¶

该插件提供以下核心能力：

seedance2_generate_image：生成图像。
seedance2_generate_video：生成视频。
seedance2_get_task：获取任务状态。
seedance2_account_help：账户帮助。

典型用法¶

以下是插件支持的使用示例。所有参考资料必须使用公共 HTTPS URL。

图像生成
使用 Seedance 2 AI Nano Banana Pro 生成一个 1:1、2K 级别的优质包装效果图，背景为干净的摄影棚地板。
视频生成
使用 Seedance 2 Pro，将一张公开的 HTTPS 开场图像转换为 5 秒钟的 720p 16:9 视频。要求使用慢推镜头效果，并生成音频。
媒体到视频
使用 Seedance 2.5，基于公开的 HTTPS 参考图像和视频生成视频。在 Prompt 中明确说明每个参考素材的作用。

提示词与参考资源¶

为了获得最佳效果，在 Prompt 中应包含以下要素：
* 主体
* 动作
* 场景
* 相机运动
* 视觉风格
* 约束条件
* 参考素材的角色

配置项¶

默认配置已具备生产环境可用性，仅在必要时覆盖。配置文件位置为 $DSH_HOME/profiles/web/cordis.patch.yml。

- id: seedance2
  config:
    apiBaseUrl: https://www.seedance2ai.io
    apiKeyEnv: SEEDANCE2_PUBLIC_API_KEY
    requestTimeoutMs: 30000
    pollIntervalMs: 3000
    imageWaitTimeoutMs: 300000
    videoWaitTimeoutMs: 900000
    maxRetries: 2
    retryDelayMs: 500
    requireApproval: true
    allowLocalHttp: false

行为与错误处理¶

幂等与重试：付费请求携带 Idempotency-Key，自动重试会复用该键。对于可重试的 429 和 5xx 响应，插件使用有界退避策略。
取消：取消操作会中止正在进行的请求和前台轮询。
超时处理：如果前台等待超时，应继续使用 seedance2_get_task 查询原始任务，避免重复付费提交。
退款信息：任务失败时会显示 API 返回的 credits_refunded。
凭证限制：插件不接受内部凭证（如 SEEDANCE_API_KEY），仅接受通过 Harness 环境变量传递的公共凭证。

生态与总结¶

该插件通过 Harness 的凭证管理解决了 API 密钥的安全暴露问题，并内置了重试、退避和超时处理逻辑，降低了集成外部视频生成模型的成本。相关文档与源码位于社区目录与 GitHub 仓库。