WaveSpeedAI

Genjutsu API:提交一个物体替换视频

使用 Genjutsu API 完成一次物体替换请求:准备源视频片段、提交任务,并获取编辑后的视频。

By John2 min read
Genjutsu API:提交一个物体替换视频

视频编辑功能可能返回一个”成功”的任务,却依然给团队留下一个无法使用的素材:处理了片段中错误的部分,替换内容在帧与帧之间发生漂移,或者根本没有人保存输出结果。对于 Genjutsu API 集成,我会让每一次编辑都能从输入到最终通过审核的文件全程可追溯。Higgsfield 的 API 快速入门介绍了提交—轮询—获取的流程;本指南将其应用于一次 Object Swap 请求。

Higgsfield 提供模型和端点。如果你的产品使用 WaveSpeedAI,请在其模型目录中确认是否有这一具体操作,并查看它自己的请求 schema。不要假定其他视频替换模型能接受 Higgsfield 的请求。

一次 Genjutsu Object Swap 请求需要什么?

一次请求需要一个源视频 URL 和一到八个参考图片 URL。提示词是可选的。resolution 默认为 720p,另外还列出了 480p 和 1080p。Object Swap API 参考文档将该模型标识为 higgsfield/genjutsu/object-swap/v1.0。它要求视频时长至少四秒,且每帧至少 409,600 像素。

提交前先检查片段。超过 30 秒的视频会被裁剪为 30 秒,输出时长也以处理后的时长为准。如果你想要的编辑发生在第 34 秒,即便请求成功,也无法交付它。请先选定片段,再记录你提交的是哪一段。

服务端请求可以采用如下形式。其中的 URL 和环境变量仅为示例:

curl -X POST \
  "https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
  -H "Authorization: Key ${HF_KEY}" \
  -H "Idempotency-Key: ${EDIT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/approved-source.mp4",
    "image_urls": ["https://example.com/approved-object.png"],
    "prompt": "Replace the featured cup with the reference cup.",
    "resolution": "720p"
  }'

请将凭据保存在你的服务器上。为每一次逻辑上的编辑分配一个稳定的幂等键,这样在提交结果不明确时可以重试,而不会有意创建出第二个任务。如果源素材中出现可识别的人物,或使用了受保护的影像或美术作品,请在上传之前取得必要的权利和同意。这是一条生产环境提醒,不构成法律建议。

提交编辑并跟踪状态

POST 成功只代表任务被接受,并不会返回成品视频。请把响应中的 request_id、status_url 和 cancel_url 与你产品中的编辑记录绑定保存。请使用返回的这些 URL,而不要自行拼接。

Higgsfield 的请求生命周期文档将 queued 和 in_progress 列为非终态。当状态变为 completed、failed、nsfw 或 canceled 时,就应停止等待。请在界面中分别展示这些结果。如果服务方已经拒绝了任务,却仍显示”仍在处理中”,这样的反馈很糟糕。

以大约两秒的间隔开始轮询,等待时间较长时再逐步拉长间隔。如果某次状态检查遇到暂时性的网络错误,就重试这次状态检查。不要仅仅因为一次轮询失败就再 POST 一次编辑。请把最终状态和返回的任何错误与请求 ID 一起保存,这样支持人员就能区分是生成失败,还是浏览器会话提前结束。

获取并检查成品视频

当状态为 completed 时,从结果中读取 video.url。把文件下载到你的产品所控制的存储中,然后检查它能否播放、是否符合预期的编辑效果。API 任务完成只是一个待交付的候选结果,并不等于审核通过。

检查时不要只看缩略图。请在片段的开头、中间和结尾检查替换效果,尤其是物体移动到其他主体后方或穿过画面的位置。把处理后的时长与你提交的片段进行对比。如果声音对该功能很重要,还要检查输出的音轨;Object Swap 参考文档没有承诺保留源音频。

单次输出效果好,并不意味着生产工作流已经就绪。服务方的”完成”只说明文件存在。是否让该文件进入产品,取决于你自己的验收检查。

让 Object Swap 在生产环境中可复现

保存可重放的编辑清单

把源素材版本、选定的时间范围、参考图片版本、提示词、分辨率、模型 ID、幂等键、请求 ID 和最终状态保存在一起。再加上通过审核的输出的存储位置。一个人可以记住参数,一个团队不能。

当编辑提出”同样的替换,但换成蓝色产品”时,这份记录就能派上用场。团队可以有意地只更改一项输入,而不必根据一个名为 final-v3.mp4 的文件去重建之前的请求。

归档原始素材和通过审核的输出

保留原始片段以便回滚,并把通过审核的结果保存到服务方的临时媒体位置之外。Higgsfield 的 API 条款中关于留存与同意的部分说明,生成的媒体至少保留七天,之后可能被删除。这并不是永久 URL 的保证。请记录结果是被接受、被拒绝还是退回修改,以及原因。

常见问题

Object Swap 会保留源片段中的音频吗?

已发布的 Object Swap 参考文档没有说明。请不要在你的产品中承诺音频透传。请用一段获得授权、带有可辨识音轨的片段进行测试,并在宣称该功能之前检查返回的文件。

排队中的 Genjutsu 请求可以取消吗?

可以,前提是它仍处于队列中且可被取消。请向返回的 cancel_url 发送取消请求;仅仅停止你的轮询器并不会取消任务。根据文档记载的生命周期,一旦开始处理,就无法再取消。

如果源 URL 在准备阶段过期会怎样?

文档没有为 Object Swap 输入 URL 过期规定一个统一的失败节点。请在 Higgsfield 可能需要获取源文件期间保持其可访问。如果准备阶段失败,请记录实际的请求状态和错误。POST 被接受并不能证明文件已经下载完成。

输入准备失败会消耗计费单位吗?

这取决于上报的失败类型。Higgsfield 的计费与留存指南说明,以 failed 或 nsfw 结束的请求不收费,预留的额度会退还。“输入准备失败”本身并不是一种计费状态,因此请检查响应和计费记录,而不要对所有此类错误套用同一条规则。

完成后的视频 URL 能保持可用多久?

生成的媒体至少可访问七天,之后可能被移除。请及时下载通过审核的视频。对于用户可能在数周之后再次访问的 Genjutsu API 功能,请从你自己的存储中提供已保存的副本。


往期文章:

分享