# What Is RunningHub and How Does Pixelle-Video Use It for Image Generation?

> Discover RunningHub, the cloud ComfyUI service powering Pixelle-Video's remote image generation and eliminating local GPU requirements.

- Repository: [AIDC-AI/Pixelle-Video](https://github.com/AIDC-AI/Pixelle-Video)
- Tags: deep-dive
- Published: 2026-04-23

---

**RunningHub is a cloud-hosted ComfyUI service that Pixelle-Video uses as a first-class workflow source for remote GPU-powered image generation, eliminating the need for local GPU resources.**

Pixelle-Video, developed by AIDC-AI, abstracts RunningHub as an alternative execution path for its ComfyUI workflows. When the source is configured as `"runninghub"`, the library does not send a local workflow file to a self-hosted ComfyUI instance. Instead, it passes the workflow's **ID** to the [ComfyKit](https://github.com/comfylabs/comfykit) client, which forwards the request to RunningHub's API. The service then returns a URL of the generated image.

---

## How RunningHub Integration Works in Pixelle-Video

The architecture follows a six-step pipeline that abstracts cloud execution behind a simple async API call.

### Step 1: Default Source Selection

The `get_default_source()` function in [`workflow_util.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/workflow_util.py) returns `"runninghub"` as the default, ensuring cloud workflows are chosen unless explicitly overridden.

**Relevant file:** [[`pixelle_video/utils/workflow_util.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/utils/workflow_util.py)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/utils/workflow_util.py)

### Step 2: Workflow Path Resolution

The `resolve_workflow_path(service, source)` function builds the string `<source>/<service>.json`. For image generation, the default call `resolve_workflow_path("image")` yields `"runninghub/image_flux.json"`.

### Step 3: Configuration Setup

The [`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml) defines the default image workflow as [`runninghub/image_flux.json`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/runninghub/image_flux.json) and requires a `runninghub_api_key` for authentication.

**Relevant file:** [[`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml)

### Step 4: Execution Branching

In `MediaService.__call__`, after parsing the workflow JSON, the code distinguishes the source:

- **RunningHub:** Passes `workflow_id` to `ComfyKit.execute(...)`
- **Self-host:** Passes the local file path

**Relevant file:** [[`pixelle_video/services/media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/media.py)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/media.py)

### Step 5: Result Handling

The returned `ExecuteResult` contains an image URL (`result.images[0]`), which is wrapped in a `MediaResult` object and returned to the caller.

### Step 6: Complete Developer Experience

This entire pipeline enables image generation with a single async call:

```python
media = await pixelle_video.media(prompt="a futuristic city at sunset")
print(media.url)  # → https://cdn.runninghub.ai/.../image.png

```

---

## Code Examples for RunningHub Image Generation

### Basic Cloud-First Image Generation

```python
import asyncio
import pixelle_video

async def generate_image():
    # Uses the default RunningHub workflow (image_flux.json)

    result = await pixelle_video.media(prompt="a serene mountain lake in sunrise")
    print("Image URL:", result.url)

asyncio.run(generate_image())

```

*Behind the scenes:* `resolve_workflow_path("image")` → `"runninghub/image_flux.json"`, and [`media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/media.py) detects `"runninghub"` to send the workflow ID to RunningHub.

### Override Workflow Explicitly

```python
result = await pixelle_video.media(
    prompt="a cyberpunk street market",
    workflow="runninghub/image_qwen.json"  # Explicit cloud workflow

)
print(result.url)

```

### Switch to Self-Hosted Workflow

```python

# In config.yaml set:

# comfyui:

#   image:

#     default_workflow: "selfhost/image_flux.json"

result = await pixelle_video.media(
    prompt="a vintage sci-fi poster",
    # No workflow argument – uses the self-hosted default

)
print(result.url)

```

### Resolve Workflow Paths Programmatically

```python
from pixelle_video.utils.workflow_util import resolve_workflow_path

cloud_path = resolve_workflow_path("image")              # "runninghub/image.json"

selfhost_path = resolve_workflow_path("image", "selfhost")  # "selfhost/image.json"

print(cloud_path, selfhost_path)

```

### Direct ComfyKit Usage with RunningHub (Advanced)

```python
from comfykit import ComfyKit
from pixelle_video.utils.os_util import get_resource_path
import json

# Load the RunningHub workflow descriptor

with open(get_resource_path("workflows", "runninghub", "image_flux.json")) as f:
    wf = json.load(f)

kit = ComfyKit()
image_url = await kit.execute(wf["workflow_id"], {"prompt": "a surreal dreamscape"})
print(image_url)

```

---

## Key Files in RunningHub Integration

| File | Role in RunningHub Image Generation |
|------|--------------------------------------|
| [[`pixelle_video/utils/workflow_util.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/utils/workflow_util.py)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/utils/workflow_util.py) | Provides `resolve_workflow_path` and the default source (`"runninghub"`) |
| [[`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml) | Shows the default cloud workflow ([`runninghub/image_flux.json`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/runninghub/image_flux.json)) and required `runninghub_api_key` |
| [[`workflows/runninghub/image_flux.json`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/workflows/runninghub/image_flux.json)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/workflows/runninghub/image_flux.json) | Minimal JSON descriptor containing the RunningHub workflow ID to invoke |
| [[`pixelle_video/services/media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/media.py)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/media.py) | Core service that decides between cloud (`runninghub`) and local (`selfhost`) execution paths |
| [[`docs/en/reference/config-schema.md`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/docs/en/reference/config-schema.md)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/docs/en/reference/config-schema.md) | Documentation of RunningHub cloud configuration including API key, concurrency, and instance type |
| [[`docs/en/user-guide/workflows.md`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/docs/en/user-guide/workflows.md)](https://github.com/AIDC-AI/Pixelle-Video/blob/main/docs/en/user-guide/workflows.md) | User guide recommending RunningHub cloud workflows for image generation without local GPU resources |

---

## Summary

- **RunningHub** is a cloud-hosted ComfyUI service that executes AI workflows on remote GPU machines, eliminating the need for local hardware

- **Pixelle-Video** uses RunningHub as a first-class workflow source via the `"runninghub"` source identifier, distinct from `"selfhost"` for local execution

- **Workflow resolution** happens through `resolve_workflow_path()` in [`workflow_util.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/workflow_util.py), defaulting to `"runninghub/image_flux.json"` for image generation

- **Authentication** requires a `runninghub_api_key` in configuration, as documented in [`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml)

- **Execution branching** in `MediaService.__call__` ([`media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/media.py)) determines whether to pass a workflow ID to `ComfyKit.execute()` (cloud) or a local file path (self-host)

- **Result handling** returns a `MediaResult` containing the generated image URL from RunningHub's CDN

---

## Frequently Asked Questions

### What is the difference between RunningHub and self-hosted ComfyUI in Pixelle-Video?

RunningHub is a managed cloud service where ComfyUI workflows execute on remote GPU machines owned by RunningHub, while self-hosted ComfyUI requires you to run your own local or remote ComfyUI instance. Pixelle-Video abstracts both through the same API—the `source` parameter (`"runninghub"` vs `"selfhost"`) determines which execution path `MediaService` takes in [`media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/media.py).

### How do I configure Pixelle-Video to use RunningHub for image generation?

Set `comfyui.image.default_workflow` to `"runninghub/image_flux.json"` in your [`config.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.yaml) and provide your `runninghub_api_key`. The default source selection in [`workflow_util.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/workflow_util.py) will automatically resolve to RunningHub workflows. You can verify your configuration by checking [`docs/en/reference/config-schema.md`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/docs/en/reference/config-schema.md) for the complete schema.

### Where does Pixelle-Video store RunningHub workflow definitions?

RunningHub workflow definitions are stored as minimal JSON descriptors in `workflows/runninghub/`, such as [`image_flux.json`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/image_flux.json). These files contain the `workflow_id` that `ComfyKit` passes to RunningHub's API, not the full workflow graph. The actual workflow execution happens remotely on RunningHub's infrastructure.