Use AI Hub with Hermes Agent

1. Prepare your workspace

Create a workspace inference key in API keys in this AI Hub environment. Give the agent its own key and choose a spend cap. Use the API base below with a key from the same environment; a console login, OpenRouter key or vendor key cannot replace it.

2. Choose your models

Find a model ID

Every AI Hub model has an author/slug ID, such as z-ai/glm-5.3-flash, in the same format OpenRouter uses. Copy IDs from AI Hub's catalogue: an ID copied from OpenRouter may not exist here or may name a different version.

1. Sign in and open Models.
2. Pick the Text tab, then narrow the list: in Capabilities choose Tools, since an agent needs tool calls, and in Context choose a large size. Hermes warns at start-up when a model holds under 64,000 tokens.
3. Select the copy button next to the model's ID.

Inside Hermes, hermes model (or /model with no arguments in a session) also lists the models AI Hub serves once the provider below is configured. That list includes non-chat models, so check a model on the Models page before using it. The page shows each model's price, context length and inputs; prices change, so check them there rather than in this guide.

Suggested models

These models call tools and hold at least 1 million tokens of context. Start with a flash model and move up when a task needs it.

3. Install and configure Hermes

Install Hermes using its official installation guide. Make BELIVE_TOKENHUB_API_KEY available through your secret manager or the private ~/.hermes/.env file. Keep it out of source control, terminal history and logs. Merge the following into ~/.hermes/config.yaml:

providers:
  tokenhub:
    api: https://tokenhub-api.belive.sg/api/v1
    key_env: BELIVE_TOKENHUB_API_KEY
    transport: chat_completions
model:
  provider: custom:tokenhub
  default: z-ai/glm-5.3-flash
fallback_providers:
  - provider: custom:tokenhub
    model: deepseek/deepseek-v4.1-flash-1017
tools:
  tool_search: false

• model.default is the primary model every session starts with.
• fallback_providers is tried in order when the primary fails, for example on a rate limit, a server error, an authentication error or a model AI Hub does not serve. Fallback normally lasts one turn, and the next message tries the primary again; after a rate limit with a reset time, Hermes stays on the fallback until that time passes. Manage the list with hermes fallback add, list, remove and clear.
• tools.tool_search: false gives the model every tool directly. With lazy tool loading on, some models write a pretend tool call as text instead of calling the tool.
• Hermes reads each model's context length from AI Hub's catalogue. It sends no output cap, so AI Hub's default for the model applies.

4. Select the model and run

hermes

For a one-shot task, pass the provider and model on the command line:

hermes -m custom:tokenhub:z-ai/glm-5.3-flash -z "Run the tests and fix the first failure"

In a disposable project, try a small task that reads a file and runs a test, then check Activity for the model, usage and cost of each request.

Switch models

In a session, switch to any AI Hub model by its ID:

/model custom:tokenhub:moonshotai/kimi-k3.1-pro

Hermes does not check the ID when you switch; a mistyped ID fails on the next request. Copy IDs from the Models page.

5. Tips

• Start cheap, then move up. A flash model handles most file editing, search and shell work. Switch to a larger model with /model for one hard task, rather than changing the default.
• Use a fallback from a different developer. A GLM primary with a DeepSeek fallback keeps working when one model is rate-limited or busy.
• Switch early, not late. Some model routes cache a repeated prompt prefix. After a /model switch or a fallback the new model has no cache, so that turn pays full input price for the whole conversation. Activity shows cache counters; see Prompt caching.
• Start a new session for an unrelated task. Each turn resends the conversation, so a long session costs more per turn.
• Give each agent its own key and spend cap. Each key's usage shows separately in Activity, and a cap stops a runaway loop.
• Check side tasks. Review auxiliary in your config: Hermes runs titles, compression and vision as side tasks, and an old override can send them to another provider. Step 6 sets the vision model.
• Restart after changing environment variables. Hermes's background gateway keeps the environment it started with; run hermes gateway stop, then start Hermes again.
• Give files as absolute paths when asking about images or videos.

See Hermes model configuration and fallback providers for every option.

6. Add media features

Media features need Hermes v0.22.5 or later. Each feature has its own block in ~/.hermes/config.yaml; merge the ones you need into the configuration from step 3. Choose each feature's model on the Models page, filtered by what it accepts and produces.

Some of these toolsets, such as video, are off by default. Enable the ones you use:

hermes tools enable vision video image_gen video_gen tts

Keep tools.tool_search: false from step 3, so the model sees the media tools directly.

Image and video understanding

Both use the vision model in auxiliary.vision. Give it the API base and an environment reference to the key. In our tests key_env did not resolve in this block and provider: custom:tokenhub failed to authenticate, so use api_key:

auxiliary:
  vision:
    base_url: https://tokenhub-api.belive.sg/api/v1
    api_key: ${BELIVE_TOKENHUB_API_KEY}
    model: qwen/qwen3.8-flash

Hermes sends images as image_url parts and videos as video_url parts with inline base64 data, which AI Hub accepts. For video, choose a model that accepts video input, and keep each file under the request body limit in Video understanding. Name the tool in your request when the agent tries other approaches first:

hermes -t vision -z "Use vision_analyze on ./photo.png and tell me what text it shows"
hermes -t video -z "Use video_analyze on ./clip.mp4 and describe what happens"

Image generation

Point Hermes's openai image provider at the tokenhub provider from step 3; it calls POST /images/generations with that provider's address and key:

image_gen:
  provider: openai
  openai:
    provider: tokenhub
    model: qwen/qwen-image-3.0

Hermes turns the requested aspect ratio into a size of 1024x1024, 1536x1024 or 1024x1536, and AI Hub accepts only the exact sizes each model lists. For the example models only the square size, 1024x1024, matches, so ask for square images; landscape and portrait requests return 400. See each model's sizes in Image generation. Reference images and edits do not work: Hermes sends them to an edits endpoint that AI Hub does not serve.

Video generation

Hermes has no setting for a custom video endpoint. Its OpenRouter video provider uses the same job API as AI Hub (submit, poll, download), so set it to AI Hub through its two environment variables, in the same place you keep BELIVE_TOKENHUB_API_KEY:

OPENROUTER_BASE_URL=https://tokenhub-api.belive.sg/api/v1
OPENROUTER_API_KEY=<your AI Hub key>

video_gen:
  provider: openrouter
  model: alibaba/wan3.0-video

hermes -t video_gen -z "Use video_generate for a 5-second 16:9 clip of a red balloon floating upward, resolution 480p"

A clip takes minutes. See Video generation for each model's durations, resolutions and prices.

Text to speech

Set the openai speech provider's base URL to AI Hub, and supply the key as VOICE_TOOLS_OPENAI_KEY:

tts:
  provider: openai
  openai:
    base_url: https://tokenhub-api.belive.sg/api/v1
    model: qwen/qwen-audio-3.0-tts-flash
    voice: loongjohn

hermes -t tts -z "Use text_to_speech to say 'Hello from AI Hub' and save it to ./hello.wav"

Hermes picks the audio format from the output file's extension, and AI Hub's named voices return WAV only, so the output path must end in .wav. Each request takes up to 600 characters. Voices for each model are in Audio.

Speech to text does not work from Hermes: it uploads the audio file in the transcription request, while AI Hub takes a file uploaded beforehand.

Troubleshooting

• Authentication failure: check the key is active in the correct workspace and environment, and available to the process running the client. Never print the key to diagnose it.
• Model missing or rejected: copy the exact catalogue ID, check key model restrictions, and check the client's selected provider and model.
• 404 or transport error: use the API base shown here, including its version prefix, without appending /chat/completions. Select Chat Completions transport.
• Tool or context errors: check supported_parameters and context_length in the catalogue; reduce the session context. See Errors for gateway responses.
• Unexpected service or missing Activity: review auxiliary models, fallbacks and local overrides. OpenRouter presets, aliases and plugins are not interchangeable with AI Hub.

Client support

Check the current model catalogue for tool support and context limits before starting a session.