Model or dataset
MetaCubeX/mihomo avatar
MetaCubeX/mihomo

mihomo: A Pydantic Wrapper for Honkai: Star Rail Player Data

A simple Python Pydantic model for Honkai: Star Rail parsed data from the Mihomo API.

35,792 stars4,777 forksPythonMIT

At a glance

What is it?
MetaCubeX/mihomo is a small Python library that maps the Mihomo API's parsed Honkai: Star Rail responses into typed Pydantic models. It gives you autocompletion and type hints, but its scope is narrow.
Who is it for?
Adopt mihomo if you build Python tools that read Honkai: Star Rail player profiles from the Mihomo API and you want type safety without writing your own models. Skip it if you need a general-purpose game data client, because it only covers this one API and this one game.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • MetaCubeX/mihomo35,792 ★ · +2,461
Star history
Repository2026-08-182026-11-15
MetaCubeX/mihomo33.3k35.8k

2,461 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What mihomo actually does

mihomo solves a narrow problem: turning the Mihomo API's parsed JSON for Honkai: Star Rail into Python objects that carry type hints and autocompletion. The API endpoint is https://api.mihomo.me/sr_info_parsed/{UID}?lang={LANG}, and the library wraps that response. The README is explicit about the scope: it is a simple Pydantic model, nothing more. If you fetch the raw JSON yourself, you get dictionaries and no editor support. With mihomo, you get classes like StarrailInfoParsed and StarrailInfoParsedV1, and fields like data.player.name are typed. The target user is a Python developer who wants to build a dashboard, a bot, or a stats tool for the game and does not want to hand-write response schemas.

Two API versions, two model sets

The API has two parsed data formats. V1 is accessed by adding version=v1 to the URL. V2 is the current default, with no version parameter. The library mirrors this split. For V1 you use client.fetch_user_v1(800333171) and import StarrailInfoParsedV1 from mihomo.models.v1. For V2 you use client.fetch_user(800333171) and import StarrailInfoParsed from mihomo.models. All models live in mihomo/models for V2 and mihomo/models/v1 for V1. This dual structure is a practical response to the API's own versioning, but it means you must know which version you are talking to. The README's example prints data.player_details.achievements, which suggests the V1 model includes player details beyond the basic player object. The split is not a cosmetic choice; it affects which fields exist and how you access them.

Installation and first fetch

Installation is a single pip command from the Git repository: pip install -U git+https://github.com/KT-Yeh/mihomo.git. There is no PyPI release mentioned, so you are tied to the repo. After installing, you create a client with a language choice, for example client = MihomoAPI(language=Language.EN). Then you await client.fetch_user(800333171) for V2 data. The README shows a full async example that prints name, level, signature, achievements, and character count. One notable option is replace_icon_name_with_url=True. Pass that to fetch_user and the parsed data comes back with asset URLs instead of icon names, saving you a separate call to client.get_icon_url. That is a small but real convenience for anyone rendering images. The client also exposes get_icon_url directly if you prefer to resolve URLs yourself.

The tools module for data cleanup

Beyond the models, the library ships a tools module that handles two data problems. First, remove_duplicate_character(data) drops duplicate character entries from a fetched profile. Second, merge_character_data(new_data, old_data) merges two fetched profiles. The README's example fetches old data, changes characters in game, waits for the API to refresh, fetches new data, and then merges the two. The intent is to keep older character records while adding new ones, which could help track changes over time. These tools are simple and specific. They do not handle arbitrary data transformations. If your use case needs custom merging logic, you will likely write your own.

Data persistence with pickle and JSON

The README includes a persistence section that shows how to save and reload fetched data. You can pickle the Pydantic object and compress it with zlib, or serialize it to JSON with data.json(by_alias=True, ensure_ascii=False). To load back, you use pickle.loads for the pickle path and StarrailInfoParsed.parse_raw(json_data) for the JSON path. The example prints the byte lengths of both formats, implying a comparison, but the README does not state which is smaller. This section is practical: it shows the model is serializable in both directions. The by_alias=True flag matters because the API may use alias field names, and the model respects that. For a caching or logging system, this gives you two storage options without extra dependencies.

Maintenance and upgrade concerns

The repository's last push was 2026-10-30, and the latest releases are v1.19.33 (2026-10-21) and v1.19.32 (2026-09-30), alongside a Prerelease-Alpha from 2024-08-12. The README does not mention a changelog or upgrade path. Because the library wraps an external API, the main upgrade risk is API changes. If Mihomo changes its response format, the Pydantic models may stop parsing correctly, and you would need to wait for a fix. The MIT license gives you freedom to fork and patch, but you should budget for that possibility.

Where mihomo is the wrong tool

mihomo is not a general game data client. It only covers Honkai: Star Rail and only the Mihomo API. If you need data from other games, or from a different API for the same game, this library will not help. The tools are limited to deduplication and merging. The client is async-only, so a synchronous script requires asyncio.run(). The README's example uses asyncio, so that is a deliberate design. If you prefer requests over aiohttp, you would need to adapt. For a hobby project that fetches a few profiles, this is fine. For a production service that polls many UIDs, you would need to build your own error handling and scheduling on top.

A real alternative: writing raw requests yourself

The obvious alternative is to skip the library and call the API with your own HTTP client. The API is a simple GET endpoint. You could use requests or httpx, parse the JSON into dictionaries, and access fields like data['player']['name']. The difference is in typing: raw dictionaries give no autocompletion, no field validation, and no error messages when the API changes shape. mihomo's Pydantic models catch mismatches at parse time. But writing your own models gives you full control over field names and aliases, and you can tune them to your exact needs. If you only need one or two fields, a raw request is lighter and has no dependency on a third-party package. If you need many fields and want type safety, mihomo saves you the initial effort. The trade-off is maintenance: you own the schema either way, but with mihomo you depend on its maintainers for updates.

Editorial conclusion

Adopt mihomo if you build Python tools that read Honkai: Star Rail player profiles from the Mihomo API and you want type safety without writing your own models. Skip it if you need a general-purpose game data client, because it only covers this one API and this one game. Before you rely on it, verify that the API version you target (v1 or v2) matches the model you import, and check whether the library still aligns with the current API response shape. The library is a thin, MIT-licensed convenience layer, not a maintained service.

Frequently asked questions

How do I install the mihomo Python model library?

The README gives one command, `pip install -U git+https://github.com/KT-Yeh/mihomo.git`, which installs a branch tip rather than a tagged release. Note that it pulls from a different GitHub account than the repository hosting the documentation, so clone the tree you actually want to test.

What is the difference between fetch_user and fetch_user_v1 in mihomo?

They read the two parsed formats the API serves. fetch_user_v1 adds version=v1 to the request and returns mihomo.models.v1.StarrailInfoParsedV1, while fetch_user reads the default format and returns mihomo.models.StarrailInfoParsed, with each format defined in its own directory.

Does mihomo work with pydantic v2?

The dependency is pinned to pydantic==1.*, and the persistence example loads saved JSON with StarrailInfoParsed.parse_raw, a pydantic v1 method. The README documents no pydantic v2 path or migration, so an environment already on v2 has to isolate this client or write its own client.

How do I cache Honkai Star Rail data fetched with mihomo?

The documented pattern compresses the model with pickle and zlib, and separately serialises it with data.json(by_alias=True, ensure_ascii=False), then reloads the JSON with StarrailInfoParsed.parse_raw. Pickle output depends on the model layout at write time, and the README documents no version stamp or migration for stored files.

What do the mihomo tools merge_character_data and remove_duplicate_character do?

remove_duplicate_character collapses repeated characters in one payload, and merge_character_data combines a new fetch with an older snapshot, which the example shows for the case where characters changed in game and the API has not refreshed. The README does not state which side wins a conflict or whether the call mutates its arguments.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/metacubex-mihomo.svg)](https://hysenlabs.com/projects/metacubex-mihomo)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/metacubex-mihomo.svg)](https://hysenlabs.com/projects/metacubex-mihomo)

Was this useful?