---
title: "Genjutsu Light Object Swap"
description: "Replace objects in a source video using reference images"
sidebar:
  label: "Object Swap"
seo:
  title: "Genjutsu Light Object Swap API Documentation: Parameters & Examples"
  description: "Genjutsu Light Object Swap API documentation: model ID higgsfield/genjutsu-light-1.0-object-swap, input modes, parameters, defaults and request examples. Replace objects in a source video using reference images."
---

{/* Generated by scripts/generate-model-pages.mjs from openapi/model-contracts.json. Do not edit; write notes in docs/models/_notes/higgsfield/genjutsu-lite-1-0.mdx */}

| Request `model` | Endpoint |
| --- | --- |
| `higgsfield/genjutsu-light-1.0-object-swap` | [Video generation](/docs/guides/video-generation) |

## Input modes

| Mode | References | Reference roles |
| --- | --- | --- |
| `reference` Reference media | 2 to 11 | `reference_image` 1 to 10<br />`reference_video` 1 |

Text is optional in these input modes on explicitly supported channels: `reference`

Prompt limit: 5,000 characters; longer prompts are rejected with 400.

## Parameters

| Parameter | Description | Values | Default | Required |
| --- | --- | --- | --- | --- |
| `duration` | Duration: Output video duration in seconds. | `4` to `30` | `5` | No |
| `resolution` | Resolution: Output resolution. | `720p`, `1080p` | `720p` | No |
| `aspect_ratio` | Aspect ratio: Output aspect ratio. | `auto` | `auto` | No |
| `generate_audio` | Generate audio: Generate native audio with the video. | `false` | `false` | No |
| `n` | Outputs per request: Number of outputs from one API request (one Job), not the application batch size. For multiple Jobs, submit separate requests; n=1 does not prevent application-managed batching. | `1` | `1` | No |

## Examples

`reference` input:

```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
  }
}
```

The authoritative contract is `GET /v1/models/higgsfield/genjutsu-light-1.0-object-swap?view=contract`. A valid parameter does not mean every channel can run it, so [quote](/docs/concepts/billing#get-a-quote) the complete request. Prices and channels are listed in [Model Market](https://yir.ai/models).

## Source video and billing

Use `input.type: "reference"` with one 4–30 second MP4 as `reference_video` and 1–10 `reference_image` inputs. In your prompt, use `@video_1` and `@image_1` to identify the source and replacement.

For object swap at 480p, use [Genjutsu Object Swap](/docs/models/higgsfield/genjutsu/object-swap). For motion transfer, use [Genjutsu Motion Transfer](/docs/models/higgsfield/genjutsu/motion-transfer). See [the Genjutsu request examples](/docs/guides/video-generation#genjutsu-motion-transfer-and-object-swap).

Yir uses NanoAPI for this model at 720p or 1080p. For a numeric quote, upload the source through [Files](/docs/guides/input-files). Estimates round up the longer measured audio or video track to whole seconds. Final billing uses the channel's actual task charge.

Higgsfield's own Genjutsu Light API processes the first 15 seconds and bills output seconds. NanoAPI accepts 4–30 second inputs and bills source seconds. [Higgsfield Light](https://open.higgsfield.ai/models/higgsfield/genjutsu-light/object-swap/v1.0/playground) · [NanoAPI Lite](https://nanoapi.ai/docs/genjutsu-lite)

## Compatible request names

Submit and quote requests also accept `genjutsu-lite-1.0`, `higgsfield/genjutsu-lite-1.0`.
