Hermes StepFun ImageGen

StepFun image generation backend for Hermes Agent.

Supports StepFun's image models:

step-image-edit-2 — recommended, fast text-to-image + image editing (1-2s)
step-2x-large — high-quality text-to-image / image-to-image
step-1x-medium — balanced quality and speed

Demo

Installation

From PyPI

pip install hermes-stepfun-imagegen[setup]   # [setup] pulls PyYAML for the setup helper
hermes-stepfun-setup                         # writes plugins.enabled + provider blocks
hermes gateway restart                       # pick up the new config

The package registers two entry points with the hermes_agent.plugins group (stepfun-imggen and image-gen-chain). Hermes auto-discovers them on next gateway start; but the loader only enables plugins that are listed in plugins.enabled in ~/.hermes/config.yaml, so the hermes-stepfun-setup one-shot is required to wire the names up. It's idempotent — re-running on an already-configured file is a no-op.

If you'd rather do it manually:

hermes plugins enable stepfun-imggen image-gen-chain

To use the fallback chain instead of the standalone StepFun backend (StepFun → MiniMax → Pollinations, useful when STEPFUN_API_KEY runs out of credits or rate-limits):

hermes-stepfun-setup --provider image-gen-chain --force-provider

From source

git clone https://github.com/lora-sys/hermes-stepfun-imagegen.git
cd hermes-stepfun-imagegen
pip install -e ".[setup]"
hermes-stepfun-setup

Manual install (no pip)

mkdir -p ~/.hermes/plugins/image_gen/{stepfun,image-gen-chain}
cp -r src/hermes_stepfun_imagegen/plugin.yaml ~/.hermes/plugins/image_gen/stepfun/plugin.yaml
# ... copy __init__.py too
hermes plugins enable image_gen/stepfun image_gen/image-gen-chain

Note the path-derived keys (image_gen/stepfun, image_gen/image-gen-chain) for the manual install — those match the bundled layout that the directory scanner walks. The pip-installed entry-point plugins use the bare entry-point name (stepfun-imggen, image-gen-chain). They're not interchangeable; pick the row that matches your install method. hermes plugins enable will tell you which keys are valid for your environment.

Quick Start

1. Set your StepFun API key

Add to ~/.hermes/.env:

STEPFUN_API_KEY=your-stepfun-api-key

2. Enable the plugin

The hermes-stepfun-setup one-shot (from the install step above) writes this block for you. If you'd rather hand-edit, the equivalent is:

plugins:
  enabled:
    - stepfun-imggen            # pip entry-point name (NOT image_gen/stepfun — that's the manual-install key)
    - image-gen-chain
    # ... other plugins

image_gen:
  provider: stepfun             # or image-gen-chain for the fallback chain
  stepfun:
    model: step-image-edit-2

Why stepfun-imggen instead of image_gen/stepfun? The pip-installed entry point declares its key as stepfun-imggen (the entry-point name). The manual ~/.hermes/plugins/image_gen/stepfun/ layout declares its key as image_gen/stepfun (path-derived). The two layouts are not interchangeable — pick whichever matches your install method. hermes plugins list shows the right key for whatever is installed.

3. Restart Hermes

hermes gateway restart

Verify the setup

hermes plugins list --json | python3 -c "import sys, json; print([p['name'] for p in json.load(sys.stdin) if 'stepfun' in p['name'] or 'chain' in p['name']])"
# Expect: ['image-gen-chain', 'stepfun-imggen']
hermes-stepfun-setup --check
# Expect: OK  /home/lora/.hermes/config.yaml

Usage

Once configured, just ask the Hermes model to generate images:

Text-to-image:

生成一张赛博朋克风格的龙

Image editing:

把这张图换成水墨画风格

Image-to-image:

把这张照片转成梵高风格

Screenshots

Text-to-Image Examples

Prompt: "A cute cat astronaut floating in space, digital art"

Prompt: "A majestic dragon perched on a cyberpunk skyscraper at sunset"

Prompt: "Traditional Chinese ink painting of mountains and rivers"

Fallback Chain

This package also ships a built-in fallback chain provider: image-gen-chain.

Priority:

stepfun — use this plugin first
minimax — fall back if StepFun is unavailable
pollinations — free anonymous fallback when the paid backends are not configured or fail

Why use the chain?

You keep StepFun as the default quality tier.
You still get outputs when StepFun is down, quota is exhausted, or the API key is missing.
The free Pollinations backend removes the single point of failure without requiring another paid account.

Setup

plugins:
  enabled:
    - stepfun-imggen
    - image-gen-chain

image_gen:
  provider: image-gen-chain
  model: step-image-edit-2

No extra env vars are required for the free Pollinations tier. Keep STEPFUN_API_KEY set for the first hop.

Behavior

The chain only falls back on provider errors, auth issues, or missing credentials.
Successful generations include extra.chain.tried and extra.chain.succeeded in the tool result.
Pollinations is used as the last resort because it is free but slower and lower fidelity than StepFun or MiniMax.

Model Comparison

Model	Speed	Quality	Best For	Edits Supported
`step-image-edit-2`	~1-2s	Good	Fast iteration, text-to-image, editing	✅ Yes
`step-2x-large`	~10-20s	High	High-quality output, image-to-image	✅ Yes
`step-1x-medium`	~10-20s	Medium	Balanced speed and quality	✅ Yes

vs Other Hermes Image Plugins

Feature	stepfun	openai	fal	krea	chain
Model	step-image-edit-2	gpt-image-2	Flux / others	Krea models	stepfun -> minimax -> pollinations
Auth	API Key	API Key	API Key	API Key	mixed; last hop is free
Speed	1-2s	15s-2min	Varies	Varies	varies by hop
Editing	✅	✅	✅	✅	✅ when available
Image-to-image	✅	✅	✅	✅	✅ when available
Local-only	❌	❌	❌	❌	❌
Cost	Paid	Paid	Paid	Paid	paid + free fallback

Model Selection

Change the default model in config.yaml:

image_gen:
  provider: stepfun
  model: step-2x-large  # or step-1x-medium

Available models:

Model ID	Display Name	Speed	Best For
`step-image-edit-2`	Step Image Edit 2	~1-2s	Fast iteration, text-to-image + editing
`step-2x-large`	Step 2X Large	~10-20s	High quality, image-to-image
`step-1x-medium`	Step 1X Medium	~10-20s	Balanced quality and speed

Configuration Options

Environment Variables

Variable	Required	Description
`STEPFUN_API_KEY`	Yes	Your StepFun API key from https://platform.stepfun.com
`STEPFUN_BASE_URL`	No	Override API base URL (default: `https://api.stepfun.com/step_plan/v1` for Step Plan subscribers)

Config.yaml Options

image_gen:
  provider: stepfun
  model: step-image-edit-2  # default model

API Reference

StepFun 开放平台: https://platform.stepfun.com
API 文档: https://platform.stepfun.com/docs/zh/api-reference/images/image
Image generation: https://platform.stepfun.com/docs/zh/api-reference/images/image
Image editing: https://platform.stepfun.com/docs/zh/api-reference/images/edits
Image-to-image: https://platform.stepfun.com/docs/zh/api-reference/images/image2image

Troubleshooting

My usage is billing my cash balance, not my Step Plan credit

Symptom: you see image-edit calls on the StepFun "账户余额" page (deducted ¥ per call) and the "Step Plan Credit 用量" page does not increment the way you expect.

Cause: the plugin is calling the open-platform endpoint https://api.stepfun.com/v1/..., which bills every call against your cash balance. Step Plan subscribers must use https://api.stepfun.com/step_plan/v1/... to draw from the subscription credit quota. Same key, different path, different meter.

Fix (one line): the default STEPFUN_BASE_URL was changed in v0.1.1 to point at /step_plan/v1/. Upgrade:

pip install --upgrade hermes-stepfun-imagegen

Or, if you've pinned the plugin path under ~/.hermes/plugins/image_gen/stepfun/, pull the latest __init__.py (search for STEPFUN_BASE_URL) and make sure the default is https://api.stepfun.com/step_plan/v1. Then restart Hermes:

hermes gateway restart

To confirm the fix is live, run a smoke test and inspect the effective base URL:

python -c "import importlib.util; m=importlib.import_module('hermes_stepfun_imagegen'); print(m.STEPFUN_BASE_URL)"
# expected: https://api.stepfun.com/step_plan/v1

Note on already-billed calls: StepFun does not refund calls that were billed against your cash balance before you switched endpoints. Going forward, calls go to credit.

If you actually want cash billing (e.g. you've used up your Step Plan quota and want to keep going with the per-image rate), explicitly override the base URL:

# in ~/.hermes/.env
STEPFUN_BASE_URL=https://api.stepfun.com/v1

See the official Step Plan image integration docs for details on the two endpoints.

Diagnostic prompt for your agent

If you ask an AI agent to debug this for you, paste the block below into a fresh chat. It walks the agent through the exact checks that matter:

You are debugging a Hermes Agent + StepFun image plugin billing issue. The user
is on a Step Plan subscription, but image generation/editing calls are being
billed against their cash balance (per-image ¥ deduction) instead of against
their Step Plan credit quota.

StepFun has TWO independent endpoints that bill DIFFERENTLY for the SAME API
key:

  - https://api.stepfun.com/v1/...            (open platform -> cash balance)
  - https://api.stepfun.com/step_plan/v1/...  (Step Plan     -> credit quota)

The plugin in ~/.hermes/plugins/image_gen/stepfun/__init__.py defaults to
STEPFUN_BASE_URL. The default was historically the cash endpoint, which
bills subscribers' cash balance. Step Plan subscribers need the /step_plan/v1
path.

Walk through these checks in order. Do not skip any. After each check, report
PASS/FAIL with the exact value you saw. When you find the problem, state the
fix in one sentence.

1. CONFIRM the plugin is the latest version. Read the file
   ~/.hermes/plugins/image_gen/stepfun/__init__.py and find the line that
   sets STEPFUN_BASE_URL. Report the literal value.

2. If the default is NOT https://api.stepfun.com/step_plan/v1, the plugin is
   on the legacy cash endpoint. That is the bug.

3. Check for env override: `grep -E '^STEPFUN_BASE_URL=' ~/.hermes/.env`
   Report whether the user has set it. If they have, that value wins over
   the default — verify it points at /step_plan/v1.

4. Check for the install path being a vendored copy under
   ~/.hermes/plugins/ (not the pip-installed version). If both exist,
   ~/.hermes/plugins/ wins because Hermes loads it first. Report which
   one is on disk.

5. Confirm the version that is actually loaded into the running gateway:
   from outside the gateway, run:
     python -c "import sys; sys.path.insert(0, '/home/lora/.hermes/hermes-agent');
                from importlib.machinery import SourceFileLoader;
                m = SourceFileLoader('p', '/home/lora/.hermes/plugins/image_gen/stepfun/__init__.py').load_module();
                print(m.STEPFUN_BASE_URL)"
   The output is what the gateway will use on the next call.

6. Suggest the smallest fix:
   - If STEPFUN_BASE_URL default is wrong: edit the file, change the default
     to https://api.stepfun.com/step_plan/v1, then `hermes gateway restart`.
   - If env override is wrong: edit ~/.hermes/.env, fix STEPFUN_BASE_URL,
     then `hermes gateway restart`.
   - If vendored copy is stale: replace it with the latest from the
     hermes-stepfun-imagegen repo, then `hermes gateway restart`.

7. After applying the fix, do an end-to-end smoke test:
     STEPFUN_API_KEY=... python -c "import importlib.util;
       m=importlib.import_module('hermes_stepfun_imagegen');
       p=m.StepFunImageGenProvider();
       r=p.generate('a tiny red circle on white', aspect_ratio='square');
       print(r['success'], r['provider'], r['model'])"
   Confirm success=True, provider=stepfun.

8. Tell the user: "Going forward, calls will bill against Step Plan credit.
   Previous calls that billed your cash balance are not refundable by
   StepFun. If you want to dispute them, contact StepFun support with your
   account ID and the date range."

Output format: a numbered list of checks with PASS/FAIL and the literal
value seen. Then ONE recommended fix command. No verbose explanation. The
user is technical.

`STEPFUN_API_KEY not set`

Make sure you've added your API key to ~/.hermes/.env:

STEPFUN_API_KEY=your-key-here

Then restart Hermes.

Plugin not loading

Check that the plugin is enabled in config.yaml:

plugins:
  enabled:
    - stepfun-imggen

And verify the pip package is installed:

python -c "import hermes_stepfun_imagegen; print(hermes_stepfun_imagegen.__file__)"

Image generation fails

Check your API key is valid at https://platform.stepfun.com
Verify you have API credits available
Check the Hermes logs for error details:

tail -f ~/.hermes/logs/errors.log

`405 Method Not Allowed` or connection errors

Make sure you're using the correct base URL. The plugin defaults to https://api.stepfun.com/step_plan/v1 (Step Plan path — billable against your subscription credit, not your cash balance). If you need the legacy platform endpoint (billed per image, paid in cash), override:

export STEPFUN_BASE_URL=https://api.stepfun.com/v1

Plugin not loading

Run hermes-stepfun-setup --check — it'll tell you exactly what's missing from plugins.enabled.

hermes plugins list --json | python3 -c "import sys, json; print([p['name'] for p in json.load(sys.stdin) if 'stepfun' in p['name'] or 'chain' in p['name']])"
# Expect: ['image-gen-chain', 'stepfun-imggen']

If those names show up but the plugin still doesn't load, run hermes-stepfun-setup to wire them into plugins.enabled.

Historical note: the loader's entry-point branch sets key=ep.name and kind="standalone", so writing plugins.enabled: [image_gen/stepfun] (the path-derived key from the manual-install layout) does NOT match an entry-point-installed plugin. Use the entry-point name (stepfun-imggen) instead. hermes plugins list will print the exact key to use.

Changelog

See CHANGELOG.md for version history and migration notes.

Development

See CONTRIBUTING.md for development setup and guidelines.

# Clone the repo
git clone https://github.com/lora-sys/hermes-stepfun-imagegen.git
cd hermes-stepfun-imagegen

# Install in editable mode
pip install -e .

# Run tests
python -m pytest tests/ -v --tb=short

# Lint
ruff check src/ tests/

# Build package
python -m build

# Verify package metadata
twine check dist/*

License

MIT

Author

lora-sys

Links

GitHub: https://github.com/lora-sys/hermes-stepfun-imagegen
PyPI: https://pypi.org/project/hermes-stepfun-imagegen/
Issues: https://github.com/lora-sys/hermes-stepfun-imagegen/issues
Hermes Agent: https://github.com/NousResearch/hermes-agent

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
docs/assets		docs/assets
src/hermes_stepfun_imagegen		src/hermes_stepfun_imagegen
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Hermes StepFun ImageGen

Demo

Installation

From PyPI

From source

Manual install (no pip)

Quick Start

1. Set your StepFun API key

2. Enable the plugin

3. Restart Hermes

Verify the setup

Usage

Screenshots

Text-to-Image Examples

Fallback Chain

Why use the chain?

Setup

Behavior

Model Comparison

vs Other Hermes Image Plugins

Model Selection

Configuration Options

Environment Variables

Config.yaml Options

API Reference

Troubleshooting

My usage is billing my cash balance, not my Step Plan credit

Diagnostic prompt for your agent

STEPFUN_API_KEY not set

Plugin not loading

Image generation fails

405 Method Not Allowed or connection errors

Plugin not loading

Changelog

Development

License

Author

Links

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`STEPFUN_API_KEY not set`

`405 Method Not Allowed` or connection errors

Packages