API Reference

AmbrAPI

Asynchronous client for interacting with the Ambr project API (gi.yatta.moe).

Provides methods to fetch various Genshin Impact game data.

Parameters:

Name	Type	Description	Default
lang	Language	The language for the API responses. Defaults to English (EN).	EN
cache_ttl	int	Time-to-live for cached responses in seconds. Defaults to 3600 (1 hour).	3600
headers	dict[str, Any] | None	Optional custom headers for HTTP requests.	None
session	ClientSession | None	Optional existing aiohttp.ClientSession to use. If None, a new CachedSession is created.	None

Attributes:

Name	Type	Description
lang		The language used for API requests.
BASE_URL	Final[str]	The base URL for the Ambr API v2.

close() async

Closes the internal aiohttp client session.

Should be called to gracefully shut down the session if not using the client as an async context manager.

fetch_abyss_data(use_cache=True) async

Fetches data for the current and potentially previous Spiral Abyss cycles.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
AbyssResponse	An AbyssResponse object containing details about abyss cycles, floors, enemies, etc.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_achievement_categories(use_cache=True) async

Fetches all achievement categories.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[AchievementCategory]	A list of AchievementCategory objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_artifact_set_detail(id, use_cache=True) async

Fetches detailed information for a specific artifact set by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the artifact set to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
ArtifactSetDetail	An ArtifactSetDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_artifact_sets(use_cache=True) async

Fetches summary information for all artifact sets.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[ArtifactSet]	A list of ArtifactSet objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_avatar_curve(use_cache=True) async

Fetches the character stat growth curves.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Name	Type	Description
	dict[str, dict[str, dict[str, float]]]	A nested dictionary representing character growth curves.
Structure	dict[str, dict[str, dict[str, float]]]	{ level: { curve_id: { stat_id: value } } }

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_book_detail(id, use_cache=True) async

Fetches detailed information for a specific book by its ID, including volumes.

Parameters:

Name	Type	Description	Default
id	int	The ID of the book to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
BookDetail	A BookDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_books(use_cache=True) async

Fetches summary information for all readable books.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Book]	A list of Book objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_changelogs(use_cache=True) async

Fetches the API changelogs.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Changelog]	A list of Changelog objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_character_detail(id, use_cache=True) async

Fetches detailed information for a specific character by their ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the character to fetch (e.g., "10000002" for Ayaka).	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
CharacterDetail	A CharacterDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_character_fetter(id, use_cache=True) async

Fetches character stories and voice-over quotes (fetter information) by character ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the character to fetch fetter data for.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
CharacterFetter	A CharacterFetter object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_character_guide(character_id, *, use_cache=True) async

Fetches community-sourced build guides for a specific character.

Combines data from sources like Genshin Wizard and genshin.aza.gg.

Parameters:

Name	Type	Description	Default
character_id	str	The ID of the character to fetch guides for.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
CharacterGuide	A CharacterGuide object containing build, playstyle, and synergy recommendations.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_characters(use_cache=True) async

Fetches summary information for all characters.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Character]	A list of Character objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_domains(use_cache=True) async

Fetches information about daily domains and their rewards for each day of the week.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
Domains	A Domains object containing lists of domains for each weekday.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_food_detail(id, use_cache=True) async

Fetches detailed information for a specific food item by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the food item to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
FoodDetail	A FoodDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_foods(use_cache=True) async

Fetches summary information for all food items.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Food]	A list of Food objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_furniture_detail(id, use_cache=True) async

Fetches detailed information for a specific furniture item by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the furniture item to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
FurnitureDetail	A FurnitureDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_furniture_set_detail(id, use_cache=True) async

Fetches detailed information for a specific furniture set by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the furniture set to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
FurnitureSetDetail	A FurnitureSetDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_furniture_sets(use_cache=True) async

Fetches summary information for all furniture sets (Serenitea Pot).

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[FurnitureSet]	A list of FurnitureSet objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_furnitures(use_cache=True) async

Fetches summary information for all furniture items (Serenitea Pot).

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Furniture]	A list of Furniture objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_latest_version() async

Fetches the latest data version hash from the API.

This hash is used internally to ensure requests use up-to-date data.

Returns:

Type	Description
str	The latest version hash string.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_manual_weapon(use_cache=True) async

Fetches manual weapon data (purpose unclear from API structure).

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
dict[str, str]	A dictionary containing the manual weapon data.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_material_detail(id, use_cache=True) async

Fetches detailed information for a specific material by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the material to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
MaterialDetail	A MaterialDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_materials(use_cache=True) async

Fetches summary information for all materials (includes ingredients, ascension items, etc.).

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Material]	A list of Material objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_monster_curve(use_cache=True) async

Fetches the monster stat growth curves.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Name	Type	Description
	dict[str, dict[str, dict[str, float]]]	A nested dictionary representing monster growth curves.
Structure	dict[str, dict[str, dict[str, float]]]	{ level: { curve_id: { stat_id: value } } }

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_monster_detail(id, use_cache=True) async

Fetches detailed information for a specific monster or living being by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the monster/being to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
MonsterDetail	A MonsterDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_monsters(use_cache=True) async

Fetches summary information for all monsters and living beings.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Monster]	A list of Monster objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_namecard_detail(id, use_cache=True) async

Fetches detailed information for a specific namecard by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the namecard to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
NamecardDetail	A NamecardDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_namecards(use_cache=True) async

Fetches summary information for all namecards.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Namecard]	A list of Namecard objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_quests(use_cache=True) async

Fetches summary information for all quests.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Quest]	A list of Quest objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_readable(id, use_cache=True) async

Fetches the text content of a specific readable item (like a book volume) by its ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the readable item to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
str	The text content of the readable item, with HTML tags removed.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_tcg_card_detail(id, use_cache=True) async

Fetches detailed information for a specific TCG card by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the TCG card to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
TCGCardDetail	A TCGCardDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_tcg_cards(use_cache=True) async

Fetches summary information for all Genius Invokation TCG cards.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[TCGCard]	A list of TCGCard objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_upgrade_data(use_cache=True) async

Fetches general upgrade material requirements for characters and weapons.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
UpgradeData	An UpgradeData object containing lists of upgrade requirements.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_weapon_curve(use_cache=True) async

Fetches the weapon stat growth curves.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Name	Type	Description
	dict[str, dict[str, dict[str, float]]]	A nested dictionary representing weapon growth curves.
Structure	dict[str, dict[str, dict[str, float]]]	{ level: { curve_id: { stat_id: value } } }

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_weapon_detail(id, use_cache=True) async

Fetches detailed information for a specific weapon by its ID.

Parameters:

Name	Type	Description	Default
id	int	The ID of the weapon to fetch.	required
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
WeaponDetail	A WeaponDetail object.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_weapon_types(use_cache=True) async

Fetches a mapping of weapon type identifiers to their display names.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
dict[str, str]	A dictionary mapping weapon type IDs (e.g., "WEAPON_SWORD_ONE_HAND") to names (e.g., "Sword").

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

fetch_weapons(use_cache=True) async

Fetches summary information for all weapons.

Parameters:

Name	Type	Description	Default
use_cache	bool	Whether to use cached data if available. Defaults to True.	True

Returns:

Type	Description
list[Weapon]	A list of Weapon objects.

Raises:

Type	Description
DataNotFoundError	If the requested data is not found (404).
ConnectionTimeoutError	If the connection times out (522, 524).
AmbrAPIError	For other API-related errors.

start() async

Initializes the internal aiohttp client session.

Must be called before making any API requests if not using the client as an async context manager. Creates a CachedSession if no session was provided during initialization.