# Hoyolab — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access character wikis, view player profiles, and browse community posts across Genshin Impact, Honkai: Star Rail, and Zenless Zone Zero. Search and discover game content, character details, and what other players are sharing in real-time.

**Category:** Entertainment | **Website:** [hoyolab.com/](https://hoyolab.com/) | **Docs:** [parse.bot/marketplace/7ff96697-4604-42e0-8563-3f540151ecd1/hoyolab-com-api](https://parse.bot/marketplace/7ff96697-4604-42e0-8563-3f540151ecd1/hoyolab-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-hoyolab-com-api-7ff96697/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_community_posts

Retrieve a feed of community posts for a specific game. Returns posts with full metadata (subject, content, images), author info, engagement stats (views, likes, replies, bookmarks), and topics. Supports cursor-based pagination via last_id. The feed can be filtered by type (hot, new, official).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `gids` | integer | No | Game ID. Accepted values: 2 (Genshin Impact), 6 (Honkai: Star Rail), 8 (Zenless Zone Zero). |
| `last_id` | string | No | Pagination cursor from a previous response's last_id field. Omit for first page. |
| `type` | integer | No | Post feed type. Accepted values: 1 (Hot), 2 (New), 3 (Official). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hoyolab-com-api-7ff96697/get_community_posts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gids":"<integer>","last_id":"<string>","type":"<integer>"}'
```

### get_user_profile

Retrieve a public HoYoLAB user profile by UID. Returns user info including nickname, avatar URL, achievement stats (posts, likes, followers), community settings, and game permissions. The profile is publicly visible unless the user has set privacy restrictions.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uid` | string | Yes | HoYoLAB User ID (numeric string, e.g. '1015537'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hoyolab-com-api-7ff96697/get_user_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uid":"<string>"}'
```

### get_wiki_character_detail

Retrieve full character details from HoYoWiki by entry_page_id. Returns the character's name, description, icon, and structured modules (Attributes with base info like VA/constellation/birthday, Ascension materials, and Gallery images). The character_id comes from get_wiki_character_list results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `character_id` | string | Yes | Wiki entry_page_id for the character (from get_wiki_character_list results, e.g. '10920'). |
| `game` | string | No | Game slug. Accepted values: genshin, hsr, zzz. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hoyolab-com-api-7ff96697/get_wiki_character_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"character_id":"<string>","game":"<string>"}'
```

### get_wiki_character_list

Retrieve a paginated list of characters from the HoYoWiki for a specific game. Each entry includes the character's name, icon URL, entry_page_id (for use with get_wiki_character_detail), and filter values such as element, weapon type, rarity, and region. Results are ordered by most recently added.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `game` | string | No | Game slug. Accepted values: genshin, hsr, zzz. |
| `page_num` | integer | No | Page number for pagination (1-based). |
| `page_size` | integer | No | Number of results per page (max 50). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hoyolab-com-api-7ff96697/get_wiki_character_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"game":"<string>","page_num":"<integer>","page_size":"<integer>"}'
```

### search_posts

Search community posts by keyword across a specific game's forum. Returns matching posts with metadata, author info, engagement stats, and pagination. Search terms in results are wrapped in highlight_tag markers. Supports offset-based pagination via last_id (maps to next_offset from previous response).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `gids` | integer | No | Game ID. Accepted values: 2 (Genshin Impact), 6 (Honkai: Star Rail), 8 (Zenless Zone Zero). |
| `keyword` | string | Yes | Search term to query community posts. |
| `last_id` | string | No | Pagination marker from a previous response's next_offset field. Omit for first page. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-hoyolab-com-api-7ff96697/search_posts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gids":"<integer>","keyword":"<string>","last_id":"<string>"}'
```