Genjutsu — Object swap API - Higgsfield API Docs

← Genjutsu Endpoint: POST https://api.higgsfield.ai/higgsfiled/genjutsu/object-swap/v1.0 Endpoint ID: higgsfiled/genjutsu/object-swap/v1.0 ▶Open API PlaygroundGenjutsu · Object swap↗

Usage notes

Use the exact API slug, including the spelling higgsfiled.
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).

Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

curl --request POST \
  --url https://api.higgsfield.ai/higgsfiled/genjutsu/object-swap/v1.0 \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
  "video_url": "https://example.com/input.mp4",
  "image_urls": [
    "https://example.com/input.jpg"
  ]
}'

import higgsfield_client

arguments = (
    {'video_url': 'https://example.com/input.mp4',
     'image_urls': ['https://example.com/input.jpg']}
)
result = higgsfield_client.subscribe(
    "higgsfiled/genjutsu/object-swap/v1.0",
    arguments=arguments,
)
print(result["video"]["url"])

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

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

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

if (result.status === "completed") {
  console.log(result.video?.url);
}

Input schema

string

default:""

Text instructions for the generation or edit. Maximum characters: 10000.

string

required

Public URL of the source video. Minimum characters: 1. Maximum characters: 2083. Format: uri.

array

required

Ordered public image reference URLs. Minimum items: 1. Maximum items: 8. Each item: string. Minimum characters: 1. Maximum characters: 2083. Format: uri.

string

default:"720p"

Output resolution tier. Allowed values: "720p", "480p".

Complete JSON schema

{
  "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"
      ],
      "type": "string",
      "title": "Resolution",
      "default": "720p"
    }
  },
  "additionalProperties": false
}

Response

Submission returns a request handle. Poll status_url until status is completed, or use webhooks.

Accepted

{
  "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"
}

A completed response includes the following output fields:

{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}

See polling, request errors and authentication for shared request handling.

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Genjutsu — Object swap API

Usage notes

Quick start

Input schema

Response

​Usage notes

​Quick start

​Input schema

​Response

Usage notes

Quick start

Input schema

Response