> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a Genjutsu Motion Transfer workflow

> Transfer motion with the Genjutsu API on GENGEN. Prepare video and image references, submit a task, poll its status, download the result, and handle errors.

Motion Transfer uses an existing video for motion and reference images for the target subject. This guide walks through preparation, submission and download.

## Prepare your inputs

* Create an [API key](https://gengen.farm/dashboard?section=apiKeys\&createKey=1), fund your wallet and review [Genjutsu pricing](https://gengen.farm/models/genjutsu#pricing).
* Host a source video of at least four seconds at a URL readable without extra headers. Only the first 30 seconds are processed.
* Host 1–8 reference images of the target subject. Use material you have permission to process.
* Choose `480p`, `720p` or `1080p`. Motion Transfer does not accept duration, aspect ratio, FPS or audio controls.

Use curl and Python 3. Set `GENGEN_API_KEY` in your local environment and keep it out of browser code and source control.

## Submit the transformation

Save this as `request.json`, replacing both placeholder URLs with accessible media:

```json request.json theme={"dark"}
{
  "model": "higgsfield-genjutsu",
  "mode": "motion_transfer",
  "prompt": "",
  "assets": {
    "sourceVideo": "https://example.com/source.mp4",
    "referenceImages": ["https://example.com/reference.png"]
  },
  "controls": { "resolution": "720p" }
}
```

The task is billable. The rate depends on mode and resolution; source-video seconds are rounded up after clipping to 30 seconds. Submit once:

```bash theme={"dark"}
curl --fail-with-body --silent --show-error \
  --connect-timeout 15 --max-time 120 \
  --request POST 'https://gengen.farm/v1/contents/generations/tasks' \
  --header "Authorization: Bearer ${GENGEN_API_KEY:?Set GENGEN_API_KEY first}" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json \
  --output task.json
```

Continue only after a successful HTTP response containing `id`. Preserve `task.json` to resume an existing task. If submission times out, check Dashboard task logs or contact [support](https://gengen.farm/support) before creating another task.

## Poll and download

Save this as `poll_video.py` and run `python3 poll_video.py`. It resumes the ID in `task.json`, retries only temporary **GET** failures, and never creates another generation task. The 30-minute polling limit is a client timeout, not a provider completion guarantee; you can resume polling later with the same file.

```python poll_video.py theme={"dark"}
import json
import os
import shutil
import time
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlparse
from urllib.request import Request, urlopen

task_id = json.loads(Path("task.json").read_text()).get("id")
if not isinstance(task_id, str) or not task_id:
    raise SystemExit("No task ID. Inspect task.json before continuing.")

endpoint = "https://gengen.farm/v1/contents/generations/tasks/"
request = Request(endpoint + quote(task_id, safe=""), headers={
    "Authorization": "Bearer " + os.environ["GENGEN_API_KEY"]
})
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
    try:
        with urlopen(request, timeout=30) as response:
            task = json.load(response)
    except HTTPError as error:
        if error.code == 429 or 500 <= error.code < 600:
            time.sleep(15)
            continue
        raise SystemExit(f"Retrieval failed with HTTP {error.code}. Check the key and task ID.")
    except (URLError, TimeoutError):
        time.sleep(15)
        continue

    status = task.get("status")
    if status in ("failed", "cancelled", "canceled", "expired"):
        Path("task-result.json").write_text(json.dumps(task, indent=2))
        raise SystemExit("Task ended: " + status + ". Inspect task-result.json.")
    if status in ("completed", "succeeded"):
        videos = (task.get("outputs") or {}).get("videos") or []
        if not videos:
            raise SystemExit("No video URL. Inspect the task and its media expiry; do not resubmit automatically.")
        output_url = videos[0]
        if not isinstance(output_url, str) or urlparse(output_url).scheme != "https":
            raise SystemExit("Unexpected output URL.")
        # Download without forwarding the API key to the media host.
        with urlopen(output_url, timeout=60) as source, open("video.mp4.part", "wb") as target:
            shutil.copyfileobj(source, target)
        Path("video.mp4.part").replace("video.mp4")
        print("Saved video.mp4 for task", task_id)
        break
    time.sleep(10)
else:
    raise SystemExit("Polling paused. Resume with the saved task ID; do not create a replacement task.")
```

Download successful outputs promptly because output URLs can expire. If the download fails, rerun the polling script with the saved ID; it will retrieve the task again without submitting a new generation.

## Handle failures before retrying

| Result | Next step |
| - | - |
| HTTP 401 or 403 | Check the bearer key and its access. Retrieve with the same account/key used for creation. |
| Insufficient balance | Check wallet funds and the requested model's current price. |
| Invalid input or inaccessible media | Correct the specified field or media URL before making a new request. |
| Content-policy rejection | Review the error and the input. A different model is not a guaranteed workaround. |
| POST timeout or unclear acceptance | Preserve the response and request time. Check task logs or contact support; do not automatically resubmit. |
| Temporary GET error | Retry retrieval with a delay using the same task ID. |

For assistance, include the task ID, model ID and error code, without your API key. See [provider troubleshooting](https://docs.gengen.farm/help/provider-errors.md) and [support](https://gengen.farm/support).

## Choose another transformation

Use the mode-specific schemas for [Object Swap](https://docs.gengen.farm/api-reference/higgsfield/genjutsu/object-swap.md) and [Restyle](https://docs.gengen.farm/api-reference/higgsfield/genjutsu/restyle.md). Restyle uses the [live style directory](https://docs.gengen.farm/api-reference/higgsfield/genjutsu/styles.md). Replacing only the `mode` field is not enough to adapt a Motion Transfer request.

See [Genjutsu workflows and pricing](https://gengen.farm/models/genjutsu) and the [full API reference](https://docs.gengen.farm/api-reference/higgsfield/genjutsu/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.