recard

Async Genshin Impact character card generator, built the same way you'd use zenka for Zenless Zone Zero: give it a UID, get back rendered card images.

pip install ./recard   # local build, see "Installing" below

import asyncio
import recard

async def main():
    async with recard.Client() as client:
        # list everything currently in the player's public showcase
        showcase = await client.get_api(700000000)
        for char in showcase:
            print(char.id, char.name, char.element)

        # render one character by name
        result = await client.card(700000000, "Hu Tao")
        for card in result.cards:
            card.card.save(f"{card.name}.png")   # card.card is a PIL.Image

        # ...or by exact avatar ID, same call shape
        result = await client.card(700000000, 10000046)

        # or render the whole showcase at once
        result = await client.card(700000000)
        for card in result.cards:
            card.card.save(f"{card.name}.png")

asyncio.run(main())

How it works / limitations

• Uses enka-py, installed automatically as the enka dependency. Public Client.get_api() and Client.card() calls keep the same interface and return types.

• Public Enka showcase access remains the default. Optional HoYoLAB access can render owned characters outside the showcase; see below.

• Character names, artwork, namecards, talents, constellations, weapons, and artifacts come from enka-py's enriched models. The four bundled metadata JSON files are no longer needed or shipped.

• enka-py downloads its metadata on first use into .enka_py/assets under the process working directory, which must be writable. First use needs an internet connection. Refresh assets after game patches:

  async with recard.Client() as client:
      await client.update_assets()
  

  The command python -m recard.data.update_data also performs this refresh. Updates depend on the upstream asset sources supporting the new characters.

• Network and parsing errors now propagate instead of appearing as an empty showcase. An empty public showcase still returns an empty list; requesting a missing character raises recard.CharacterNotFound.

• Custom splash art is read from ~/.recard/custom_splash/<char_id>.(png|jpg|jpeg|webp).

• Internal JSON-path constructor options and old placeholder HoYoLAB hooks were removed. Integrations using those internals should use the public Client.

Optional HoYoLAB cards (0.3.0)

Install the optional dependency from this extracted project folder:

python -m pip install ".[hoyolab]"

After publishing this version to PyPI, users can install it with:

python -m pip install --upgrade "recard[hoyolab]"

Pass each user's own cookie dictionary when creating their client:

import os
import recard

cookies = {
    "ltuid_v2": os.environ["LTUID_V2"],
    "ltoken_v2": os.environ["LTOKEN_V2"],
}

async with recard.Client(cookies=cookies) as client:
    roster = await client.get_api(uid, source="hoyolab")
    result = await client.card(uid, "Hu Tao", source="hoyolab")
    # IDs also work: client.card(uid, 10000046, source="hoyolab")
    for card in result.cards:
        card.card.save(f"{card.id}.png")

source="enka" remains the default, even if cookies are supplied. HoYoLAB mode is explicit and independent of the public showcase. Omitting a character in HoYoLAB mode renders the returned owned roster; this may take time for large accounts. Selecting a character downloads only that character's detailed build.

The library verifies that the requested Genshin UID belongs to a linked account before requesting its roster or details. Use region="cn" for Miyoushe cookies; the default is region="os" for HoYoLAB. Each Client keeps a private copy of its cookie mapping in memory, with no global cookie account or cookie files. In a multi-user bot, create a Client using the requesting user's cookies.

Missing cookies, unlinked UIDs, failed authenticated requests, and incomplete details raise recard.HoYoLABError. HoYoLAB can require fresh cookies or account verification. The library does not change privacy settings or bypass verification. Missing characters raise recard.CharacterNotFound.

HoYoLAB cards now use enka-py's cached character metadata for namecard backgrounds, without requiring a public showcase. Banner artwork is tried first, then the full namecard. Characters without a namecard (such as Traveler), missing metadata, or unavailable artwork use a neutral background. Run await client.update_assets() to refresh metadata after game patches.

Custom images (0.3.1)

Works with both source="enka" and source="hoyolab":

async with recard.Client(cookies=cookies, splash_directory="data/custom_splash") as client:
    # Save by character ID, like the bot's !add_splash command.
    client.set_custom_image(10000046, "my-hu-tao.png")
    result = await client.card(uid, "Hu Tao", source="hoyolab")
    for card in result.cards:
        card.card.save(f"{card.id}.png")

    # Override only this call; leave the saved image unchanged.
    result = await client.card(uid, "Hu Tao", source="hoyolab",
                               custom_image="another-image.jpg")

    # Remove the saved image to restore official artwork.
    client.remove_custom_image(10000046)

Image arguments accept a local path, encoded image bytes, or a Pillow image. Saved images are normalized to PNG. Existing ID-named PNG/JPG/JPEG/WebP files in the configured folder are also recognized. The default folder remains ~/.recard/custom_splash. A one-time override takes priority over the saved image; saved images take priority over official artwork. Custom images keep the bot's left-aligned crop and fade, while the namecard remains the background. If rendering multiple cards at once, a one-time override is applied to every card. For a multi-user bot, use a separate splash directory per user.

See examples/hoyolab_card.py for a runnable example using environment variables. The Telegram bot's cookie-entry and storage interface is outside this library.

Verification

Install the HoYoLAB extra, then run python -m unittest discover -s tests -v. Tests cover public and authenticated selection, account ownership checks, cookie isolation, error redaction, stat units, artifact levels, talents and rendering. Authenticated requests are mocked; a live cookie-authenticated request has not been verified for this release. Public Enka rendering was verified in 0.2.0.

Installing

This isn't published to PyPI yet. Until then:

pip install ./recard
# or, for local editing:
pip install -e ./recard

Once published:

pip install recard

License

The code in this repository is MIT-licensed - see LICENSE.

Note on bundled assets: recard/assets/ ships fonts, icons, and character art from Genshin Impact, © COGNOSPHERE PTE. LTD. / HoYoverse. These are included for card rendering purposes only, are not covered by this project's MIT license, and all rights to them remain with their original owner. This project is an unofficial fan tool and is not affiliated with or endorsed by HoYoverse.

The enka-py dependency has its own GPL-3.0 license; see its repository for details.