---
title: "Genjutsu Light 对象替换"
description: "用参考图替换源视频中的物体"
sidebar:
  label: "对象替换"
seo:
  title: "Genjutsu Light 对象替换 API 文档：参数与调用示例"
  description: "Genjutsu Light 对象替换 API 文档：模型 ID higgsfield/genjutsu-light-1.0-object-swap、输入模式、参数取值与默认值，附请求示例。用参考图替换源视频中的物体。"
---

{/* 由 scripts/generate-model-pages.mjs 根据 openapi/model-contracts.json 生成，请勿手改；补充说明写在 docs/zh/models/_notes/higgsfield/genjutsu-lite-1-0.mdx */}

| 调用时的 `model` | 接口 |
| --- | --- |
| `higgsfield/genjutsu-light-1.0-object-swap` | [视频生成](/zh/docs/guides/video-generation) |

## 输入模式

| 模式 | 参考数量 | 参考角色 |
| --- | --- | --- |
| `reference` 参考素材 | 2–11 | `reference_image` 1–10<br />`reference_video` 1 |

以下输入模式可在明确支持的渠道省略文字： `reference`

提示词上限：5000 个字符，超出时返回 400。

## 参数

| 参数 | 说明 | 取值 | 默认值 | 必填 |
| --- | --- | --- | --- | --- |
| `duration` | 时长：输出视频的秒数。 | `4`–`30` | `5` | 否 |
| `resolution` | 分辨率：输出内容的分辨率。 | `720p`、`1080p` | `720p` | 否 |
| `aspect_ratio` | 画幅：输出内容的宽高比。 | `auto` | `auto` | 否 |
| `generate_audio` | 生成音频：随视频生成原生音频。 | `false` | `false` | 否 |
| `n` | 单次请求输出数量：单次 API 请求（一个 Job）的输出数量，不是应用的批量张数。应用可提交多个独立请求组成一批；n=1 不表示应用只能生成一张。 | `1` | `1` | 否 |

## 示例

`reference` 输入：

```json
{
  "model": "higgsfield/genjutsu-light-1.0-object-swap",
  "input": {
    "type": "reference",
    "prompt": "A paper boat drifting down a rainy city street, slow tracking shot",
    "references": [
      {
        "role": "reference_image",
        "file_id": "file_..."
      },
      {
        "role": "reference_video",
        "file_id": "file_..."
      }
    ]
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "generate_audio": false,
    "n": 1
  }
}
```

完整合同以 `GET /v1/models/higgsfield/genjutsu-light-1.0-object-swap?view=contract` 为准。参数合法不代表每个渠道都能执行，请对完整请求[报价](/zh/docs/concepts/billing#获取报价)。价格与渠道见[模型市场](https://yir.ai/zh/models)。

## 源视频与计费

设置 `input.type: "reference"`，传一段 4–30 秒的 MP4 作为 `reference_video`，再传 1–10 张 `reference_image`。提示词可用 `@video_1` 和 `@image_1` 指明源视频与替换图。

需要 480p 对象替换时，请用 [Genjutsu Object Swap](/zh/docs/models/higgsfield/genjutsu/object-swap)。需要动作迁移时，请用 [Genjutsu Motion Transfer](/zh/docs/models/higgsfield/genjutsu/motion-transfer)。请求写法见[幻术动作迁移与对象替换](/zh/docs/guides/video-generation#幻术动作迁移与对象替换)。

Yir 通过 NanoAPI 执行，支持 720p 或 1080p。需要金额估价时，先用 [Files](/zh/docs/guides/input-files) 上传源视频。估价取实测音频轨和视频轨中较长的一条并向上取整到整秒，最终按渠道的任务实扣结算。

Higgsfield 的 Genjutsu Light API 处理源视频前 15 秒，按输出秒数计费。NanoAPI 接收 4–30 秒的源视频，按源视频秒数计费。[Higgsfield Light](https://open.higgsfield.ai/models/higgsfield/genjutsu-light/object-swap/v1.0/playground) · [NanoAPI Lite](https://nanoapi.ai/docs/genjutsu-lite)

## 兼容调用名

提交和报价也接受 `genjutsu-lite-1.0`、`higgsfield/genjutsu-lite-1.0`。
