Higgsfield Genjutsu API 实操：动作迁移、物体替换与风格重绘三条端点跑通
Genjutsu 不止能用在网页里：动作迁移、物体替换、风格重绘，都有对应的 REST 端点
站内 9527 教过在 Higgsfield 网页里用 Genjutsu 把一段实拍视频换角色换场景。如果你想把同样的能力接进自己的产品或自动化流程里，走的是另一条路：开发者 API。官方在 docs.higgsfield.ai 为 Genjutsu 开放了三条工作流端点——motion-transfer（动作迁移）、object-swap（物体替换）、restyle（风格重绘），一个 API Key 通吃，按秒计费。本篇属于 Higgsfield 实战手册，把三条端点的参数表、请求示例、轮询流程和实测踩到的鉴权坑走一遍。相关背景见站内 AI 工具导航，产品主页在 Higgsfield。
先给全貌。三条工作流的参数结构高度相似，差异集中在必填字段与输入限制上：
三条工作流端点与硬性限制对照（下方流程条是一次调用的五步生命周期），依据官方模型文档绘制
开始之前：API 和你的 Higgsfield 套餐是两个账户
最容易误解的一点先说清楚：网页版订阅、积分、Unlimited 与 API 完全不互通。API 跑在独立账户上，控制台在 open.higgsfield.ai，计费用美元预付余额，最低充值 5 美元，按生成结果计费，余额用尽后新请求自动排队而不是报错。官方帮助中心的对照表值得先看一遍再决定要不要开账号：
三条接入通道对照：Genjutsu API 走最右列，与网页版积分互不相通
几个直接影响决策的数字：创建一把 API Key 解锁 20 并发请求；生成文件至少保留 7 天，之后可能从服务器清除；失败的生成不收费，金额自动退回余额。Genjutsu 在 API 目录里的现价是 5 折后的 $0.159/秒（原价 $0.318/秒），Restyle 另按分辨率计价——480p 约 $0.318/秒、720p 约 $0.681/秒、1080p 约 $1.632/秒，官方注明是近似单价而非报价单，落单前用 estimate 端点核一次最稳。
鉴权：Authorization 头与一个实测确认
凭证在 Higgsfield Console 里创建，一把凭证包含 key ID 和 secret 两段。调用时放进一个头里：
Authorization: Key YOUR_KEY_ID:YOUR_KEY_SECRET
官方文档同时接受旧版 hf-api-key 与 hf-secret 双头写法，但新集成建议统一用 Authorization。本篇在未注册账号的状态下实测了三个端点，把鉴权墙的行为先摸清楚：
实测截图：motion-transfer 提交、伪造 Key 的 object-swap 提交、presets 目录 GET，三路全部返回 401 Invalid credentials
三条请求拿到同一个响应：{"detail":"Invalid credentials"}。这个行为和官方 Authentication 文档写明的 401 格式逐字一致，也说明两件事：其一，鉴权在进入模型逻辑之前就拦截，参数错误不会暴露给未认证请求；其二，缺 Key、坏 Key 返回完全相同，排障时错误信息不会告诉你差在哪一段，先用 console 里能看到的凭证重试，别对着报错猜。另一个容易忽略的点：Restyle 的风格目录（presets）也在鉴权墙后，也就是说 preset_id 必须拿到真实 Key 才能拉取，文档示例里的 UUID 不能直接照抄提交。
动作迁移：motion-transfer 的最小调用
端点是 POST https://api.higgsfield.ai/higgsfield/genjutsu/motion-transfer/v1.0。必填只有两个字段：源视频 video_url 和参考图数组 image_urls（1 到 8 张，有序）。官方 curl 示例原文如下：
curl --request POST \ --url https://api.higgsfield.ai/higgsfield/genjutsu/motion-transfer/v1.0 \ --header "Authorization: Key ${HF_A...RET}" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \ --data '{ "video_url": "https://example.com/input.mp4", "image_urls": [ "https://example.com/input.jpg" ] }'
—— Genjutsu Motion transfer 官方文档 Quick start 节
提交后立即返回一个请求句柄，生成是异步的：
{
"status": "queued",
"request_id": "REQUEST_ID",
"status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
"cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}
接下来轮询 status_url 直到 completed，或者配 webhook 等通知。completed 响应里 video.url 就是成片下载地址。终态有四种：completed、failed、nsfw、canceled，官方特别提醒拿到请求句柄不等于生成成功——素材下载失败、风格不可用这类错误可能发生在受理之后，failed 响应会带 error 信息，轮询逻辑要处理满四种终态。
可选参数只有两个：prompt（文本指令，上限 10000 字符，可空串）和 resolution（480p / 720p / 1080p，默认 720p）。schema 里 additionalProperties: false——多塞一个字段直接校验失败，别把其他模型的参数顺手带过来。
物体替换：object-swap 与像素下限
端点换成 POST .../higgsfield/genjutsu/object-swap/v1.0，参数结构与 motion-transfer 完全一致：video_url 加 image_urls，同样的 prompt 与 resolution。差异在输入限制：官方 Usage notes 里写明源视频每帧至少 409,600 像素（约等于 854×480）。低分辨率素材（比如从聊天工具里转了几道手的压缩视频）会在准备阶段被拒掉，交付前先核一遍源视频的分辨率。
两条工作流共享的限制：源视频至少 4 秒；超过 30 秒只取前 30 秒，输出时长跟随处理后的源视频。也就是说想用一部 2 分钟的素材做替换，要么先自己剪出 30 秒以内的段落，要么接受官方只处理开头。
风格重绘：restyle 与 preset 目录
restyle 是三条里参数最不同的一条。必填字段变成 video_url 加 preset_id——后者是一个 UUID，必须先调风格目录接口拿：
curl --fail-with-body --silent --show-error \
'https://api.higgsfield.ai/models/higgsfield/genjutsu/restyle/v1.0/presets' \
-H "Authorization: Key ${HF_A...RET}"
返回的 items[].id 才是 preset_id，name 和 preview_url 都只是给人看的，填进去会被拒。目录会随官方上下架变动，文档原话是「如果保存的选中项消失了，刷新列表重选」，写死 UUID 的集成要有降级准备。角色参考图 image_urls 在 restyle 里是可选的（最多 5 张）：不传或传空数组，直接对源视频里现有的主体和场景做风格化；传了则每张角色图被风格化、源场景背景单独清理后再合成。
restyle 的边界条件官方写得相当细：源视频 4 到 30 秒、最大 200 MiB；保留源视频原有音频，且没有更换配乐的控制项；输出构图来自源视频，但时长和帧率可能与源不完全一致。官方还明确列出这条端点不暴露的能力：批量大小的数值、时长、宽高比、FPS、场景模式、独立背景图、seed、供应商选择都不在参数表里——想做「同一请求出 N 条」的批量逻辑，得在外层自己循环。
SDK 与版本口径
除了裸 REST，官方提供 Python 与 TypeScript 两枚 SDK。本文核对当日，PyPI 上 higgsfield-client 最新版 0.2.0（2026-09-17 上传，要求 Python 3.8+），npm 上 @higgsfield/client 最新版 0.2.6（同日发布）。Python 侧的 subscribe 写法一行拿到轮询结果：
import higgsfield_client
arguments = (
{'video_url': 'https://example.com/input.mp4',
'image_urls': ['https://example.com/input.jpg']}
)
result = higgsfield_client.subscribe(
"higgsfield/genjutsu/motion-transfer/v1.0",
arguments=arguments,
)
print(result["video"]["url"])
SDK 的 subscribe 封装了提交加轮询，等价于裸 REST 里「POST 之后循环查 status」那一段。凭据配置方式两个 SDK 不同（Python 走环境约定，TS 走 config({ credentials })），以各自文档为准。
排障清单：文档里白纸黑字的坑
第一条坑在素材入口：官方要求源视频与参考图是不带浏览器 Cookie、不带自定义鉴权头的可下载 URL，未过期的签名 HTTPS 链接可以用；本地文件先走 file uploads 换直链，URL 长度上限 2083 字符。把内网地址或带登录态的页面链接填进 video_url，受理能通过，素材下载会在后台失败。
可空字段别传 null。restyle 文档明写「Defaults apply to omitted optional fields. Use [] or an empty string where appropriate; null is not accepted」——该空就传空数组或空串。
提交超时没拿到 request_id 时，用同一个 Idempotency-Key 重发即可，不会重复扣费生成两条；新生成才换新 Key。
从旧教程或旧代码里抄端点时，先数一遍字母。官方文档原话：旧端点 higgsfiled/genjutsu/.../v1.0（higgsfield 少了个 s）仍对老客户端开放，但已从模型发现里隐藏——新集成一律用 higgsfield/... 拼写。
最后是留存问题：成片在服务器上至少保留 7 天，之后可能清除。长期留存要在 completed 后把 video.url 的文件转存到自己的存储，别把生成链接当永久地址写进业务库。
来源与延伸
本文步骤、参数表与代码示例依据 docs.higgsfield.ai 的 Genjutsu 模型文档（motion-transfer / object-swap / restyle 三页）及官方帮助中心《What is the Higgsfield API》整理，401 实测为本机真实请求记录，版权归原作者所有。界面版 Genjutsu 的用法见站内 9527。
