RunningHub Seedance 2.0 API 配置：密钥、资源与首次调用

AI Overview

配置 RunningHub Seedance 2.0 API 的最快方式是什么？

创建一个 RunningHub API 密钥，选择确切的 Seedance 2.0 AI 应用或模型路由，发送一个最简请求，然后轮询其 taskId。仅在该首次调用成功后，再添加上传、Webhook 和生产环境重试机制。

我应使用 AI App API 还是 ComfyUI 工作流？

当您需要一个固定、托管的输入契约时，请使用 AI App API；当您的团队需要可见的节点映射、可复用的图结构、资源预处理，或项目间频繁变更的模型步骤时，请使用 ComfyUI OpenAPI 路由。

Seedance 2.0 资源 ID 在 RunningHub 中如何工作？

资源 ID 使受支持的 Seedance 2.0 节点能够复用已准备好的引用。ComfyUI 集成接受纯 ID、asset:// 格式值、逗号分隔列表，或 JSON 数组字符串，但所选节点仍决定有效的输入插槽。

为何需立即复制已完成任务的 URL？

RunningHub 为上传内容和生成结果提供临时媒体链接。任务成功后，请立即将每个已批准的 MP4 文件及 poster 移至您自主管控的持久化存储中；已保存的任务 ID 并非永久媒体归档。

首次调用前所需准备

可靠的配置始于四个确定值：API 区域、有效密钥、精确的 AI 应用或模型标识符，以及您可控的存储目标。切勿直接复制无关教程中的端点，并假定其请求体兼容。RunningHub 暴露多种调用风格，而每个已发布的 API 详情页即为该路由的契约。更全面的 Seedance 2.0 API 指南 解释了通用异步模式；本指南则聚焦于 RunningHub。

请将密钥置于源码控制之外。对于官方 ComfyUI 集成，文档推荐的环境变量配置模式如下：

export RH_API_BASE_URL="https://www.runninghub.cn/openapi/v2"
export RH_API_KEY="replace-with-your-key"

请使用您个人 RunningHub 控制台及当前文档中显示的区域化基础 URL。消费者密钥可能需满足特定会员资格，而企业密钥则可能适用不同的访问规则。请将“在目录中可见某模型”与“使用您的密钥调用该模型”视为两项独立校验。

在消耗积分前，请先定义一个验收样例：单一主体、单一动作、单一镜头运动、单一持续时间、单一输出宽高比。若您不确定提示词本身是否可行，可先在 Seedance 2.0 模型工作区 中测试创意简报，从而将提示词问题与集成问题区分开来。

首次调用请采用视觉简洁的验收帧。此全新产品图像便于检查轮廓、反射、水流动态及背景稳定性；它并非 RunningHub 基准测试图像。

选择正确的 RunningHub 路由

RunningHub 为此任务提供两条实用路径。AI 应用路由适用于服务提供商已将 Seedance 2.0 封装为具备命名输入的稳定应用的情形——您向该应用 ID 提交请求并获得一个 taskId。当图结构本身属于您的生产逻辑，或您需要其 Seedance 2.0 资源辅助功能时，ComfyUI OpenAPI 插件更为合适。

首次测试中请勿混用上述路由。最小化的 AI 应用请求应能验证身份认证、应用标识符、队列提交及结果获取；最小化的 ComfyUI 调用则应验证导出工作流能否原样运行，之后再引入动态 nodeInfoList 覆盖配置。

官方 RunningHub ComfyUI 插件可从设置节点、环境变量或 .env 文件读取配置，其中节点设置优先级最高。请记录密钥来源的具体层级；否则，当同事轮换环境密钥时，旧节点中残留的值可能仍会静默生效。

资源密集型镜头应确保人物、服饰、动物、天气及地点清晰可辨。该图像为全新示意性输出，并非官方模型对比结果。

RunningHub Seedance 2.0 API 分步配置指南

从仅暴露您服务真正可控变量的请求骨架开始。RunningHub 当前 AI 应用文档所示端点格式为 /run/ai-app/{appId}，返回含 QUEUED、RUNNING、SUCCESS 或 FAILED 等状态的任务对象。请以对应 API 详情页上生成的请求示例为准，作为字段名称的唯一可信来源。

const response = await fetch(`${RUNNINGHUB_BASE}/run/ai-app/${APP_ID}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nodeInfoList: inputMappings,
    webhookUrl: process.env.RH_WEBHOOK_URL
  })
});

if (!response.ok) throw new Error(`Submit failed: ${response.status}`);
const task = await response.json();
```对于一个 ComfyUI 工作流，请导入任一匹配的示例，**仅在未使用环境配置时**连接 `RH OpenAPI Settings`，并使用静态值运行该图。待其正常运行后，仅暴露需变动的节点——即 prompt、reference、duration、ratio 或输出选项，并将这些节点 ID 与工作流版本一同存储。

RunningHub 的 Seedance 2.0 资产工具提供了另一条路径。`real_person_mode=false` 将沿用直传（direct-upload）路径；启用后，所选本地图像或视频插槽将在模型请求前被转换为资产。`conversion_slots` 控制参与转换的插槽。请先测试单张图像，因为包含九张图像与三段视频的负载会掩盖具体是哪个映射导致失败。

```official-video
src=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-v1.mp4
poster=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-poster-v1.jpg
label=用于校验 API 检索结果的垂直产品环绕视频

此可播放的 Seedance 运动输出展示了检索后应检查的内容：稳定的产品几何结构、受控的相机运动以及干净的画面帧。它并非作为 RunningHub 基准测试呈现。

构建可穿越 API 边界的输入

API 无法推断哪个文件是首帧、终帧、角色参考图或风格参考图。提交前请先构建输入清单（input manifest）。其中应包含本地文件名、源文件校验和（checksum）、MIME 类型、目标插槽（intended slot）、若已创建则附资产 ID，以及指向该文件的 prompt 标签。这比仅存放一个名为 final-2.png 的文件夹更有价值。

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "中景跟拍镜头；厨师摆盘；蒸汽升腾；温暖实用光源",
  "ratio": "16:9"
}

文档中所述的 ComfyUI 集成支持以下任一格式：单个资产 ID、形如 asset://<asset_ID> 的值、逗号或换行符分隔的多个值，或 JSON 数组字符串。这种灵活性虽便利，但一致性更安全：请在代码库中统一选用一种表示方式，并在图运行前完成校验。对于图像转视频任务，该集成会识别 first_frame 和 last_frame；多模态视频节点则可暴露多个图像与视频插槽。建议使用 reference-to-video 工作区 在自动化前优化参考包。

将 prompt 编写为可执行的镜头指令：分别明确构图（framing）、主体（subject）、动作（action）、环境（environment）、光照（light）与声音（sound）。若首次调用在创意层面失败，请仅简化其中一个维度，而非同时更改端点、资产、prompt 与工作流。图像转视频 prompt 工作流 提供了一种可复用的 prompt 模式。

此全新完成帧展示了一次测试结果：手部清晰可辨、食物几何结构准确、蒸汽升腾自然、实用光照真实——这四个细节均值得在整个生成片段中逐一核查。

轮询、存储与审阅结果

提交后，请先持久化保存返回的 taskId，再开始轮询。采用带上限的指数退避策略；遇到终端失败（terminal failure）即停止；确保轮询操作幂等，以便重启的工作器能继续处理同一任务。若您的路由支持 webhook，请在将载荷视为可信前，验证其签名或共享密钥。回调逻辑应更新现有任务记录，而非新建第二代任务。

在状态为 SUCCESS 时，请立即复制 MP4 文件。RunningHub 明确指出：生成结果链接与上传链接可能在 24 小时后过期。因此，仅当人工打开审阅界面时才下载文件是不安全的。请将文件本身、校验和、服务商任务 ID、prompt 版本、源清单（source manifest）及生成时间戳一并存储。随后，仅当您的交付栈（delivery stack）有需要时，再生成 poster 与浏览器可播放的代理文件（proxy）。

用于审阅细微运动的咖啡与蒸汽动态片段

此第二个真实运动输出采用克制的手部动作、升腾的蒸汽与阳光效果，为审阅者提供了不同于产品环绕视频的另一类失效面（failure surface）。

请审阅完整视频片段，而不仅限于首帧。评分维度包括：身份一致性（identity）、物体几何结构（object geometry）、运动连续性（motion continuity）、相机路径（camera path）、背景稳定性（background stability）、音画匹配度（audio fit）及交付安全性（delivery safety）。一项技术上成功的任务，仍可能完全不可用。对于涉及多个模型或服务商的活动，多模型 AI 视频工作流 展示了如何在不同路由间统一审阅标准。

织物走向、手部形态、足部接触、地平线稳定性与相机高度共同构成一份针对高运动量结果的精简验收清单。

修复常见 RunningHub Seedance 2.0 API 错误

按生命周期阶段分类处理错误：

• 返回 401 或 403 状态码，通常指向密钥、区域、成员资格或权限问题，而非 prompt 本身；
• 请求在返回 taskId 前即被拒绝，往往说明端点地址、应用 ID、内容类型（content type）或请求体结构（body shape）有误；
• 任务进入队列后长期无进展，通常是队列阻塞或超时问题；
• FAILED 任务若附带内容校验详情（content verification detail），则需采用更安全的 prompt 或参考素材；
• SUCCESS 任务却返回过期 URL，则属于存储层故障。| 症状 | 首先检查 | 纠正措施 | |---|---|---| | 未授权 | 密钥来源与基础区域 | 移除陈旧的节点覆盖；轮换密钥并针对最小调用重新测试 | | 节点映射无效 | 工作流版本与节点 ID | 导出现有图谱，仅更新已命名的节点 | | 资产转换失败 | 插槽名称、类型及源可访问性 | 单独测试一个插槽；使用文档中指定的直传回退方案 | | 任务持续处于排队状态 | 轮询间隔与账户队列 | 主动退避；切勿自动创建重复任务 | | 结果 URL 已过期 | 持久化存储事件 | 仅当原始文件从未被复制时，才重新运行 | | 片段视觉效果异常 | 提示词与源清单（manifest） | 保持 API 不变，仅调整一个创意变量 |

记录状态码、提供商错误码、任务 ID、工作流版本及脱敏后的字段名。切勿记录 API 密钥或完整的私有媒体 URL。即使提供商接口未暴露幂等性键（idempotency key），也应在您自己的服务中添加该键；此举可防止客户端重试导致重复扣费。

若集成在技术层面已正常运行，但协调过程正成为瓶颈，请使用 Seedance Agent 来组织参考素材、将简报转化为分镜、比对已批准输出，并仅重跑失败阶段。这是生产层决策，而非对底层 API 原理理解的替代方案。

结论

一套稳健的 RunningHub Seedance 2.0 API 配置是一项生命周期工程，而非单次成功的 cURL 命令：选择正确的 AI 应用或 ComfyUI 接口路径；将密钥置于代码之外；验证一次最小化调用；显式映射资产；持久化保存 taskId；轮询时主动退避；立即复制临时结果；并依据书面验收清单全面评估成片。待上述边界稳定后，再逐步引入 Webhook、更广泛的多模态输入、批量调度及人工审批——切勿以额外自动化掩盖故障。为在投入资源前即规划参考素材与分镜，并让已批准内容贯穿评审流程及选择性重跑环节，请从 Seedance Agent 启动项目。