> For the complete documentation index, see [llms.txt](https://animotive.gitbook.io/animotive-kimodo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://animotive.gitbook.io/animotive-kimodo/setup/remote-backend.md).

# Self-Hosted (HTTP) Backend

The **Self-Hosted (HTTP)** backend talks to a Kimodo FastAPI server that your team or organisation operates. The plugin sends each generation as an HTTP request and streams progress back over WebSocket, surfacing every lifecycle state in the **Kimodo Monitor** panel.

This page covers the editor-side configuration. The companion server is a separate deployment concern — once the server is reachable, the only setup left is filling in a handful of fields under **Edit → Project Settings → Plugins → Kimodo Exporter**.

## When to use Self-Hosted (HTTP)

Animotive Kimodo ships with three backends. Self-Hosted (HTTP) sits between the two extremes:

| Backend                                                                   | Hosting                              | Setup effort                           | When it fits                                                                                               |
| ------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [Local (Docker)](/animotive-kimodo/setup/docker-local.md)                 | Your machine, via Docker Desktop     | Local Docker, local GPU                | Solo workstation with a capable GPU, low-latency iteration, no shared infrastructure.                      |
| **Self-Hosted (HTTP)**                                                    | A server your team runs              | Reach the server URL, set a model name | A shared internal Kimodo server already exists, or a team wants one machine to do the solves for everyone. |
| [Animotive Kimodo (hosted)](/animotive-kimodo/setup/animotive-backend.md) | Managed cloud service from Animotive | API key, no infrastructure             | Zero-setup managed option, token-metered billing.                                                          |

Self-Hosted (HTTP) is the right choice when someone in your organisation has stood up a Kimodo FastAPI server and the editor host can reach it over the network. If you have not deployed a server and do not plan to, choose [Local (Docker)](/animotive-kimodo/setup/docker-local.md) or [Animotive Kimodo (hosted)](/animotive-kimodo/setup/animotive-backend.md) instead.

> **Self-Hosted is distinct from Animotive Kimodo (hosted).** Both backends share the same HTTP transport, WebSocket monitor, and result-download path in the plugin, but the request body, 202 envelope, URL schemes, and 4xx classification differ. Choosing **Remote Server** points the plugin at a self-deployed FastAPI server you configure here; choosing **Animotive** points it at the built-in hosted endpoint with an API key. Do not paste the Animotive endpoint into the **Server URL** field — it will not work.

## Prerequisites

Editor-side, there are no additional prerequisites beyond the base plugin install covered in [Plugin Install](/animotive-kimodo/setup/plugin-install.md). In particular, Docker Desktop is **not** required for this backend — the plugin makes ordinary HTTP and WebSocket calls.

Server-side, the Kimodo FastAPI server must be deployed and reachable from the editor host.

> **NVIDIA's Kimodo distribution does not ship HTTP endpoints.** The open-source Kimodo release provides the `kimodo_gen` / `kimodo_demo` / `kimodo_textencoder` CLIs and a local `localhost:7860` web demo, but no HTTP API. To use the Self-Hosted (HTTP) backend, someone on your team must stand up a FastAPI service that exposes the request schema the plugin speaks and proxies generation requests to a running `kimodo_gen` process. The contract — request body, async submission flow, WebSocket progress format, BVH response shape, reconnect policy — is documented in [Advanced → Remote API Reference](/animotive-kimodo/advanced/remote-api.md); that page is the reference your infrastructure or pipeline team works from.

If your team does not have the capacity to author a FastAPI wrapper, use [Local (Docker)](/animotive-kimodo/setup/docker-local.md) or [Animotive Kimodo (hosted)](/animotive-kimodo/setup/animotive-backend.md) — the hosted service handles the server side for you.

From the animator's seat, once the server is reachable, the only thing that matters is that the server URL responds and that the model name matches what the server expects.

## Configure plugin settings

Open **Edit → Project Settings → Plugins → Kimodo Exporter**. The panel header reads **Kimodo Importer** — that is the same panel. Under **Active Backend**, choose **Remote Server**. The Remote Server fields become visible and the Docker fields stay hidden until you switch back.

The fields exposed for this backend are:

| Setting                     | Default                        | Purpose                                                                                                                                                                                                                                                                                                                                         |
| --------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Server URL`                | (your team's value)            | Base URL of the Kimodo FastAPI server, in the form `http(s)://host:port`. No trailing slash. The endpoint path is appended to this value at request time.                                                                                                                                                                                       |
| `Endpoint Path`             | `/api/projects/generate/async` | Path appended to `Server URL` for each generation. The default targets the async submission route, which streams progress over WebSocket. The legacy synchronous route is `/api/generate`.                                                                                                                                                      |
| `Remote Kimodo Model`       | `kimodo-soma-rp`               | Model identifier sent with the request. The server expects the lowercase-hyphen form (contrast with the Docker backend, which expects `Kimodo-SOMA-RP-v1`).                                                                                                                                                                                     |
| `Request Timeout (Seconds)` | `300`                          | Maximum time a single generation request is allowed to take before the client gives up. Five minutes is enough for typical multi-prompt scenes; raise it for long or constraint-heavy generations.                                                                                                                                              |
| `Auth Header`               | empty                          | Optional value passed verbatim as the HTTP `Authorization` header (for example `Bearer <token>`). Leave empty to disable the header. The open-source Kimodo server treats this as a stub and does not currently require auth; it becomes required when targeting the [Animotive Kimodo (hosted)](/animotive-kimodo/setup/animotive-backend.md). |
| `Enable Server-Side Cancel` | off                            | Reserved for servers that implement the cancel endpoint. Leave off unless you operate a server that has shipped the cancel route. When off, the **Cancel** button on in-flight monitor rows stays disabled with an explanatory tooltip.                                                                                                         |

### Server URL

The **Server URL** field takes your team's Kimodo server URL. Format it as a scheme, host, and port with no trailing slash — for example `http://kimodo.example.internal:8000` or `https://kimodo.example.com`. The plugin appends **Endpoint Path** to this value for each generation; if you include a trailing slash, the resulting URL will contain a double slash and requests will fail.

If the server is fronted by TLS, use `https://`. The plugin derives the WebSocket scheme from the URL automatically — `http` maps to `ws`, `https` maps to `wss`.

### Endpoint Path

The default `/api/projects/generate/async` selects the async submission route. On this route the plugin POSTs the request, receives a 202 envelope with a `job_id` and a `websocket_url`, connects to the WebSocket, and forwards every lifecycle event into the monitor. Progress feedback is live: stage, segment, diffusion step, and percentage all update in real time on both the toast and the monitor row.

The legacy `/api/generate` route is kept for back-compat with deployments that have not shipped the async route. On the legacy route, the plugin POSTs the request and waits for the final BVH in a single HTTP response, with stage-only progress feedback rather than live updates. Leave the default unless your server team has explicitly told you to use the legacy path.

### Model name

The **Remote Kimodo Model** field is the source of the most common gotcha when switching backends. The Docker backend expects `Kimodo-SOMA-RP-v1` (title-case with version suffix). The HTTP server expects `kimodo-soma-rp` (lowercase with hyphens, no suffix). Each backend has its own model field in settings; the value is not shared. After switching the **Active Backend** dropdown, confirm the model field on the backend you are switching *to* matches what that backend expects.

### Auth Header

Most self-hosted deployments of the open-source server run inside a private network and do not require an Authorization header. In that case, leave **Auth Header** empty.

If the server is behind a gateway that enforces tokens, put the full header value here — including the scheme. The plugin sends the field verbatim. A common form is `Bearer <token>`. The field is also where the [Animotive Kimodo (hosted)](/animotive-kimodo/setup/animotive-backend.md) token will be set when that backend ships.

The [First-Run Setup popup](/animotive-kimodo/setup/first-run-setup.md)'s **API Key** field writes to this same setting. The popup labels it differently for animator-facing clarity, but the underlying storage is identical — there is one value, exposed under two names depending on where you edit it.

### Server-Side Cancel

`Enable Server-Side Cancel` is off by default. When off, the **Cancel** action on in-flight monitor rows is disabled and the row tooltip explains that server-side cancel is not enabled for this backend. When on, cancelling a row POSTs to the server's cancel endpoint and the row moves to **Cancelled** when the server confirms.

Only turn this on if the server you target has shipped the cancel route. If you turn it on against a server that does not implement cancel, the request will fail and the row will remain in flight until the generation completes naturally or the request timeout elapses.

## Async vs synchronous endpoint

The two endpoints differ in how progress reaches the editor.

| Mode            | Endpoint Path                  | Transport             | Progress feedback                                      |
| --------------- | ------------------------------ | --------------------- | ------------------------------------------------------ |
| Async (default) | `/api/projects/generate/async` | HTTP POST + WebSocket | Live: stage, segment index, diffusion step, percentage |
| Sync (legacy)   | `/api/generate`                | HTTP POST only        | Stage-only, five discrete steps                        |

The async path is the default for new deployments. The sync path is preserved for legacy compatibility and is functionally complete — generations still succeed — but the toast and monitor row only update at stage boundaries. Unless your server team has explicitly told you to use `/api/generate`, leave the default in place.

## Request lifecycle in the monitor

Every generation produces one row in the **Kimodo Monitor** panel. On the async path, the row walks through the following states:

1. **Queued** — request submitted, waiting for the server to pick it up.
2. **Uploading** — request body in flight to the server.
3. **Processing** — Kimodo is solving the in-betweens. The progress bar fills as diffusion steps and segments complete.
4. **Downloading** — solve finished, BVH being transferred back to the editor.
5. **Retargeting** — BVH imported and retargeted onto your character.
6. Terminal state: **Completed**, **Failed**, or **Cancelled**.

Open the panel via **Tools → Animotive Kimodo → Monitor**. Rows persist across editor restarts; in-flight rows on the previous run are auto-cancelled when the editor shuts down. Failed rows expose a right-click **Copy error** action that puts the friendly error message on the clipboard.

## First-run checklist

Before submitting your first generation against a self-hosted server, work through the following:

1. **Active Backend** is set to **Remote Server** in **Edit → Project Settings → Plugins → Kimodo Exporter**.
2. **Server URL** is filled in with your team's value and contains no trailing slash. Confirm it is reachable from the editor host — `curl -sf "$URL/healthz"` from a terminal on the same machine is a quick smoke test if the server exposes a health route.
3. **Endpoint Path** is `/api/projects/generate/async` (or the legacy path if your server team has instructed otherwise).
4. **Remote Kimodo Model** is `kimodo-soma-rp` — not the Docker title-case form.
5. **Request Timeout (Seconds)** is at least `300`; raise for long scenes.
6. **Auth Header** is set if and only if your server enforces tokens.
7. **Enable Server-Side Cancel** is off unless your server has shipped the cancel route.

Run a small generation from [Quick Start](/animotive-kimodo/getting-started/quick-start.md) to verify the path end-to-end. A successful row reaches **Completed** with an imported `UAnimSequence` on the binding.

## Common HTTP-specific issues

The friendly error text on each row identifies the layer at which the failure surfaced. The three most common HTTP-specific categories are:

* **`NetworkUnreachable` — "Couldn't reach the Kimodo server. Check your connection or contact pipeline."** The plugin could not open an HTTP or WebSocket connection. Verify **Server URL** is correct and reachable, the server is running, and the editor host can route to it. WebSocket reconnect runs three attempts at 1 s / 2 s / 4 s backoff before raising this category.
* **`RemoteServerError` — "Kimodo server returned an error or no data. Try again or contact pipeline."** The server accepted the request but the response was missing required fields or the async lifecycle ended in `event=failed`. A 2xx with no `job_id` and a `failed` event with no `error_message` both land here. Inspect `<ServerUrl>/openapi.json` to confirm the routes the server actually publishes, and ask your server team to check its logs for the `job_id` from the monitor row.
* **`ServerSolveFailed` — "Kimodo couldn't solve this animation. Try simplifying the prompt or adjusting key poses."** The server received the request and ran the model, but the model itself could not produce a result. Simplify the prompt, shorten the duration, or move the key poses closer to one another and retry.

A frequent cause of `RemoteServerError` immediately after switching backends is a model-name mismatch — for example, leaving `Kimodo-SOMA-RP-v1` (the Docker form) in **Remote Kimodo Model**. Confirm the model field matches the lowercase-hyphen form `kimodo-soma-rp` the server expects.

See [Troubleshooting](/animotive-kimodo/going-further/troubleshooting.md) for the full symptom table.

## Switching backends

The **Active Backend** dropdown can be changed at any time. When switching from **Remote Server** to **Docker (Local)**, the Remote Server fields disappear from the panel and the Docker fields appear in their place — the Docker model field needs its own value, and the Docker compose and export paths need to be configured per [Local (Docker) Backend](/animotive-kimodo/setup/docker-local.md). Switching back to **Remote Server** restores the Remote Server fields with the values previously entered. The plugin does not migrate or copy values between backends; each backend's settings are independent.

## See also

* [Local (Docker) Backend](/animotive-kimodo/setup/docker-local.md) — run Kimodo on your machine through Docker Desktop.
* [Animotive Kimodo (hosted)](/animotive-kimodo/setup/animotive-backend.md) — managed cloud generation service from Animotive (future release).
* [Remote API Reference](/animotive-kimodo/advanced/remote-api.md) — request schema, async submission lifecycle, retargeter resolution, and reconnect policy, for server operators and integrators.