Mihomo: A Python Pydantic Model for Honkai: Star Rail API Data

If you’ve ever tried to work with Honkai: Star Rail’s API data in Python, you know it can get messy fast. The raw JSON from miHoYo’s endpoints is full of nested fields, vague keys, and inconsistent naming. That’s where Mihomo comes in.

Mihomo is a Python package (hosted on GitHub under MetaCubeX) that wraps Honkai: Star Rail API responses into clean, type-validated Pydantic models. It’s basically a schema layer on top of the game’s data – no more guessing whether "equip" is a weapon or an artifact, or why "avatar" sometimes means character and sometimes means profile picture.

What It Does

Mihomo ingests the API responses from Honkai: Star Rail’s public endpoints and converts them into hierarchical Pydantic models. This means you get:

• Strict type checking – Every field is defined with Python types (int, str, list, Optional, etc.).
• Automatic validation – If the API sends unexpected data, Pydantic throws errors instead of silently breaking your app.
• Nested structure – Things like character builds, light cones, relics, and stats are broken into separate, easy-to-navigate classes.
• Serialization – Once validated, your models can be saved as JSON or any format you need.

Under the hood, it uses Pydantic v2, so you get modern features like model_validate and model_dump out of the box.

Why It’s Cool

The real win here is developer experience. Writing your own parser for a game API is tedious and error prone. Mihomo does the heavy lifting – you just import the models and pass your JSON in.

A few highlights:

• Full coverage – Handles everything from basic player profiles to detailed character stats, light cones, relics, and substats. No more manually fishing for fields.
• Readable code – The models are named clearly (e.g., PlayerInfo, Character, RelicSet), so your project stays readable and maintainable.
• Lightweight – No huge dependencies beyond Pydantic. It’s a thin wrapper, not a full SDK.
• Community maintained – The MetaCubeX group has a solid track record with similar tools (like their miHoYo API wrapper for Genshin).

If you’re building a companion app, a stats tracker, a Discord bot, or just want to explore the game’s data without losing your mind, this saves hours of manual mapping.

How to Try It

It’s a standard Python package. Install via pip:

pip install mihomo

Then grab some JSON from Honkai: Star Rail’s API (e.g., the player info endpoint) and parse it:

from mihomo import MihomoAPI
import json

client = MihomoAPI()
data = client.fetch_player(uid="123456789")  # Replace with a real UID

You get back validated Pydantic models. From there, you can access anything – data.player.name, data.characters[0].light_cone.name, etc.

For more examples, check the GitHub repo. There’s also a simple CLI tool if you prefer testing without writing Python – just run mihomo after install.

Final Thoughts

Mihomo isn’t flashy – it’s a utility tool. But for anyone building on top of Honkai: Star Rail’s public API, it’s exactly the kind of thing you wish existed. Instead of writing brittle parsers or debugging JSON paths, you get clean, typed objects that work with your editor’s autocomplete and your linter’s type checks.

If you’re a dev who enjoys game data analysis, bot building, or just tinkering with API responses, give it a spin. It’s small, practical, and does one thing well – which is more than most libraries can say.

Follow us on X: @githubprojects