# Genjutsu

> One video. Endless ways to reimagine it.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0`
- **Model ID**: `higgsfield/genjutsu/object-swap/v1.0`
- **Category**: video2video
- **Kind**: inference
- **Tags**: featured, trending

## Pricing

Per-second pricing. Each second of input video costs $0.318 at 480p, $0.681 at 720p, $1.632 at 1080p. Input duration is rounded up to the nearest whole second. Rates shown are before any applicable customer discount.

## Authentication

Keep credentials in server-side environment variables. The SDKs accept the same `KEY_ID:KEY_SECRET` value under their documented variable names.

```bash
export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL
```

The official SDKs configure the authorization header. Keep credentials server-side; the TypeScript SDK blocks browser use.

## API Information

Use `subscribe` to submit the model request and wait for a terminal result. TypeScript performs automatic polling with `withPolling: true`; Python's synchronous `subscribe` call also waits.

### Input Parameters

- **`prompt`** (`string`, _optional_):
  - Default: `""`

- **`video_url`** (`string`, _required_):

- **`image_urls`** (`list<string>`, _required_):

- **`resolution`** (`string`, _optional_):
  - Default: `"720p"`
  - Options: `720p`, `480p`, `1080p`

### Input JSON Schema

```json
{
  "type": "object",
  "title": "ObjectSwapParams",
  "required": [
    "video_url",
    "image_urls"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "default": "",
      "maxLength": 10000
    },
    "video_url": {
      "type": "string",
      "title": "Video Url",
      "format": "uri",
      "maxLength": 2083,
      "minLength": 1
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "maxLength": 2083,
        "minLength": 1
      },
      "title": "Image Urls",
      "maxItems": 8,
      "minItems": 1
    },
    "resolution": {
      "enum": [
        "720p",
        "480p",
        "1080p"
      ],
      "type": "string",
      "title": "Resolution",
      "default": "720p"
    }
  },
  "additionalProperties": false
}
```

### Required Parameters Example

```json
{
  "prompt": "",
  "video_url": "https://example.com/input.mp4",
  "image_urls": [
    "https://example.com/input.jpg"
  ],
  "resolution": "720p"
}
```

### Output Schema

The shared polling endpoint returns one of the following status shapes:

```json
{
  "title": "RequestStatus",
  "oneOf": [
    {
      "title": "PendingRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "in_progress",
            "nsfw",
            "canceled"
          ]
        }
      },
      "required": [
        "status",
        "request_id"
      ]
    },
    {
      "title": "FailedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "failed"
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "status",
        "request_id",
        "error"
      ]
    },
    {
      "title": "CompletedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "completed"
        },
        "video": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "zip": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "mov": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "jsx": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "fbx": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "ply": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        }
      },
      "required": [
        "status",
        "request_id",
        "video"
      ]
    }
  ]
}
```

## SDK Installation

Install one of the official server-side SDKs:

```bash
npm install @higgsfield/client
# or
pip install higgsfield-client
```

## Usage Examples

### TypeScript

```typescript
import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "higgsfield/genjutsu/object-swap/v1.0",
  {
    input: {
      "prompt": "",
      "video_url": "https://example.com/input.mp4",
      "image_urls": [
        "https://example.com/input.jpg"
      ],
      "resolution": "720p"
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'higgsfield/genjutsu/object-swap/v1.0',
    arguments={'prompt': '',
         'video_url': 'https://example.com/input.mp4',
         'image_urls': ['https://example.com/input.jpg'],
         'resolution': '720p'},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "",
  "video_url": "https://example.com/input.mp4",
  "image_urls": [
    "https://example.com/input.jpg"
  ],
  "resolution": "720p"
}
JSON
```

## Additional Documentation

# About

**Genjutsu Object Swap** uses the model ID `higgsfield/genjutsu/object-swap/v1.0`. The source video must be at least 4 seconds. Videos longer than 30 seconds are trimmed to 30 seconds; output duration follows the prepared source video. Provide 1–8 image references. The prompt is optional and defaults to an empty string. The source video must contain at least 409,600 pixels per frame (width × height).

## 1. Calling the API

Send requests to `https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0` with a JSON body matching the parameters below.

### Install

Install an official server-side SDK. cURL needs no package.

```bash control=package group=install-typescript variant=npm label=npm when=javascript
npm install @higgsfield/client
```

```bash control=package group=install-python variant=pip label=pip when=python
pip install higgsfield-client
```

### Setup

Keep credentials in server-side environment variables. The SDKs accept the same `KEY_ID:KEY_SECRET` value under their documented variable names.

```bash
export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL
```

### Request parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `prompt` | `string` | No | `""` | Prompt. Maximum length: 10000. |
| `video_url` | `string` | Yes | `—` | Video Url. Minimum length: 1. Maximum length: 2083. |
| `image_urls` | `array[string]` | Yes | `—` | Image Urls. |
| `resolution` | `string` | No | `"720p"` | Resolution. Options: 720p, 480p, 1080p. |

## 2. Authentication

The official SDKs read credentials from the server environment and send the required `Authorization: Key KEY_ID:KEY_SECRET` header.

### API Key

Never expose the secret in browser-side code or commit it to source control. The TypeScript SDK is server-side only. For direct HTTP calls, use:

```http
Authorization: Key $HF_KEY
```

## 3. Queue

`subscribe` submits the asynchronous request and waits for a terminal result. The TypeScript SDK polls automatically when `withPolling: true`; the Python SDK's synchronous `subscribe` call also waits. A completed request returns the generated file in the `video` field.

### Submit and wait

```ts control=language group=submit variant=javascript label=TypeScript
import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "higgsfield/genjutsu/object-swap/v1.0",
  {
    input: {
      "prompt": "",
      "video_url": "https://example.com/input.mp4",
      "image_urls": [
        "https://example.com/input.jpg"
      ],
      "resolution": "720p"
    },
    withPolling: true,
  },
);

console.log(result);
```

```python control=language group=submit variant=python label=Python
import higgsfield_client

result = higgsfield_client.subscribe(
    'higgsfield/genjutsu/object-swap/v1.0',
    arguments={'prompt': '',
         'video_url': 'https://example.com/input.mp4',
         'image_urls': ['https://example.com/input.jpg'],
         'resolution': '720p'},
)

print(result)
```

```bash control=language group=submit variant=curl label=cURL
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "",
  "video_url": "https://example.com/input.mp4",
  "image_urls": [
    "https://example.com/input.jpg"
  ],
  "resolution": "720p"
}
JSON
```

### Explicit lifecycle control

Use the Python SDK when a worker needs explicit status, result, or cancellation control for an existing request. The TypeScript v2 client currently exposes automatic polling through `subscribe`.

```python
import higgsfield_client

request_id = "{request_id}"
status = higgsfield_client.status(request_id=request_id)
result = higgsfield_client.result(request_id=request_id)
higgsfield_client.cancel(request_id=request_id)
```

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/higgsfield/genjutsu/object-swap/v1.0)
- [This LLM-readable document](https://dash.higgsfield.ai/models/higgsfield/genjutsu/object-swap/v1.0/llms.txt)