Skip to content

README.md

Latest commit

 

History

History
356 lines (294 loc) · 7.97 KB

README.md

File metadata and controls

356 lines (294 loc) · 7.97 KB
Raw

HoYoverse API

A REST API that provides redemption codes, event calendars, and news for HoYoverse games.

Supported Games

Game Slug
Genshin Impact genshin
Honkai: Star Rail starrail
Zenless Zone Zero zenless
Honkai Impact 3rd honkai
Tears of Themis themis

Base URL

All endpoints are prefixed with /mihoyo.

Endpoints

API Info

GET /mihoyo/

Returns API version, uptime, and a list of available endpoints.

Response:

{
  "message": "HoYoverse Redemption Code API",
  "version": "1.0.0",
  "uptime": 3600,
  "endpoints": [...]
}

Redemption Codes

GET /mihoyo/{game}/codes

Returns active and inactive redemption codes for the specified game.

Path Parameters:

Parameter Type Description
game string Game slug (see supported games table)

Response:

{
  "active": [
    {
      "code": "GENSHINGIFT",
      "rewards": ["Primogems x60", "Mora x10000"]
    }
  ],
  "inactive": [
    {
      "code": "OLDCODE123",
      "rewards": ["Primogems x30"]
    }
  ]
}

Event Calendar

Available for Genshin Impact, Honkai: Star Rail, and Zenless Zone Zero.

GET /mihoyo/genshin/calendar
GET /mihoyo/starrail/calendar
GET /mihoyo/zenless/calendar

Returns current events, character/weapon banners, and challenges.

Query Parameters:

Parameter Type Default Description
lang string en-us Language for calendar content

Example:

GET /mihoyo/genshin/calendar?lang=ja-jp
GET /mihoyo/starrail/calendar?lang=ja
GET /mihoyo/zenless/calendar?lang=zh-cn

Supported language codes and aliases are the same as the News endpoints.

Genshin Impact Response:

{
  "events": [
    {
      "id": 1,
      "name": "Event Name",
      "description": "Event description",
      "image_url": "https://...",
      "type_name": "In-Game",
      "start_time": 1700000000,
      "end_time": 1700100000,
      "rewards": [
        {
          "id": 1,
          "name": "Primogem",
          "icon": "https://...",
          "rarity": "5",
          "amount": 420
        }
      ],
      "special_reward": null
    }
  ],
  "banners": [
    {
      "id": 1,
      "name": "Banner Name",
      "version": "4.5",
      "characters": [
        {
          "id": 1,
          "name": "Character Name",
          "icon": "https://...",
          "element": "Pyro",
          "rarity": 5
        }
      ],
      "weapons": [
        {
          "id": 1,
          "name": "Weapon Name",
          "icon": "https://...",
          "rarity": 5
        }
      ],
      "start_time": 1700000000,
      "end_time": 1700100000
    }
  ],
  "challenges": [
    {
      "id": 1,
      "name": "Spiral Abyss",
      "type_name": "Abyss",
      "start_time": 1700000000,
      "end_time": 1700100000,
      "rewards": [],
      "special_reward": null
    }
  ]
}

The Star Rail calendar response follows the same structure but with light_cones instead of weapons, and characters/light cones include an additional path field.

Zenless Zone Zero Response:

{
  "events": [
    {
      "id": 18000003,
      "name": "Event Name",
      "state": "STATE_IN_PROGRESS",
      "image_url": "https://...",
      "start_time": 1700000000,
      "end_time": 1700100000,
      "polychrome": 400
    }
  ],
  "banners": [
    {
      "banner_type": "GACHA_TYPE_CHARACTER_UP",
      "state": "GACHA_STATE_IN_PROGRESS",
      "version": "3.0",
      "agents": [
        {
          "id": 1561,
          "name": "Agent Name",
          "full_name": "Full Agent Name",
          "icon": "https://...",
          "rarity": "S",
          "profession": "anomaly",
          "element": "Wind"
        }
      ],
      "w_engines": [
        {
          "id": 14156,
          "name": "W-Engine Name",
          "icon": "https://...",
          "rarity": "S",
          "profession": "anomaly"
        }
      ],
      "start_time": 1700000000,
      "end_time": 1700100000
    }
  ],
  "challenges": [
    {
      "id": 1,
      "name": "Deadly Assault",
      "type_name": "deadly_assault",
      "start_time": 1700000000,
      "end_time": 1700100000
    },
    {
      "id": 2,
      "name": "Threshold Simulation",
      "type_name": "threshold_simulation",
      "start_time": 1700000000,
      "end_time": null
    },
    {
      "id": 3,
      "name": "Shiyu Defense",
      "type_name": "shiyu_defense",
      "start_time": null,
      "end_time": null
    },
    {
      "id": 4,
      "name": "Annihilation Simulacrum",
      "type_name": "annihilation_simulacrum",
      "start_time": 1700000000,
      "end_time": 1700100000
    }
  ]
}

Zenless challenge names follow the requested lang where official localization is available; type_name remains stable across languages. Italian and Turkish currently fall back to English challenge names because the official Zenless localization bundle does not provide those locales. Available dates use Unix seconds converted from game server time. Upstream missing, invalid, or inactive period dates return null.

News

GET /mihoyo/{game}/news/events
GET /mihoyo/{game}/news/notices
GET /mihoyo/{game}/news/info

Returns the latest HoYoLab community posts for the specified game, categorized by type.

Path Parameters:

Parameter Type Description
game string Game slug (see supported games table)

Query Parameters:

Parameter Type Default Description
lang string en-us Language for news content

Supported languages:

Code Full locale
en / en-us English
zh / zh-cn Chinese (Simplified)
zh-tw Chinese (Traditional)
de / de-de German
es / es-es Spanish
fr / fr-fr French
id / id-id Indonesian
it / it-it Italian
ja / ja-jp Japanese
ko / ko-kr Korean
pt / pt-pt Portuguese
ru / ru-ru Russian
th / th-th Thai
tr / tr-tr Turkish
vi / vi-vn Vietnamese

Response:

[
  {
    "id": "12345",
    "title": "Version 4.5 Update Notice",
    "description": "Dear Travelers, below are the details of the Version 4.5 update...",
    "created_at": 1700000000,
    "banner": "https://...",
    "url": "https://www.hoyolab.com/article/12345",
    "type": "notice"
  }
]

The type field matches the endpoint used: "event", "notice", or "info".

Error Handling

All errors follow a consistent format:

{
  "status": "Not Found",
  "error_code": 1000,
  "error": "Unknown game: invalid_game"
}

Error Codes:

Code Name Description
404 ROUTE_NOT_FOUND The requested endpoint does not exist
1000 UNKNOWN_GAME The game slug is not recognized
1001 INVALID_LANGUAGE The lang parameter is not a supported language
2000 DATABASE_ERROR A database operation failed
3000 NOT_CONFIGURED The requested feature is not configured on the server
3001 UPSTREAM_ERROR An upstream HoYoverse/HoYoLab API call failed

Rate Limiting

The API enforces IP-based rate limiting. Default limits are 2 requests per second with a burst allowance of 120 requests. Requests exceeding the limit will receive a 429 Too Many Requests response.

Caching

Responses are cached in memory to reduce load on upstream services:

  • Redemption codes: 5 minutes
  • Calendar data: 5 minutes
  • News: 15 minutes

Reporting Invalid Codes

If you find any redemption codes that are incorrectly parsed or have wrong reward information, please create an issue and include the following:

  • The redemption code in question
  • The game it belongs to
  • A description of what is incorrect (e.g., wrong rewards listed, code marked as active when expired, etc.)