# Hoyolab — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/hoyolab/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/hoyolab/get-community-posts \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/hoyolab/get-user-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/hoyolab/get-wiki-character-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/hoyolab/get-wiki-character-list \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/hoyolab/search-posts \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"gids":"<integer>","keyword":"<string>","last_id":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.