Skip to content

AnimeTrace

Classes

AnimeTrace

Bases: BaseSearchEngine[AnimeTraceResponse]

API client for the AnimeTrace image search engine.

Used for performing anime character recognition searches using AnimeTrace service.

Attributes:

Name Type Description
base_url str

The base URL for AnimeTrace API.
is_multi Optional[int]

Whether to show multiple results, 0 or 1.
ai_detect Optional[int]

Whether to enable AI image detection, 1 for yes, 2 for no.
Source code in PicImageSearch/engines/anime_trace.py 
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class AnimeTrace(BaseSearchEngine[AnimeTraceResponse]):
    """API client for the AnimeTrace image search engine.

    Used for performing anime character recognition searches using AnimeTrace service.

    Attributes:
        base_url (str): The base URL for AnimeTrace API.
        is_multi (Optional[int]): Whether to show multiple results, 0 or 1.
        ai_detect (Optional[int]): Whether to enable AI image detection, 1 for yes, 2 for no.
    """

    def __init__(
        self,
        base_url: str = "https://api.animetrace.com",
        endpoint: str = "v1/search",
        is_multi: Optional[int] = None,
        ai_detect: Optional[int] = None,
        **request_kwargs: Any,
    ):
        """Initializes an AnimeTrace API client with specified configurations.

        Args:
            base_url (str): The base URL for AnimeTrace API, defaults to 'https://api.animetrace.com'.
            endpoint (str): The endpoint for AnimeTrace API, defaults to 'v1/search'.
            is_multi (Optional[int]): Whether to show multiple results, 0 or 1, defaults to None.
            ai_detect (Optional[int]): Whether to enable AI image detection, 1 for yes, 2 for no, defaults to None.
            **request_kwargs (Any): Additional arguments passed to the HTTP client.
        """
        base_url = f"{base_url}/{endpoint}"
        super().__init__(base_url, **request_kwargs)
        self.is_multi: Optional[int] = is_multi
        self.ai_detect: Optional[int] = ai_detect

    @override
    async def search(
        self,
        url: Optional[str] = None,
        file: Union[str, bytes, Path, None] = None,
        base64: Optional[str] = None,
        model: Optional[str] = None,
        **kwargs: Any,
    ) -> AnimeTraceResponse:
        """Performs an anime character recognition search on AnimeTrace.

        This method supports three ways of searching:
            1. Search by image URL
            2. Search by uploading a local image file
            3. Search by providing a base64 encoded image

        Args:
            url (Optional[str]): URL of the image to search.
            file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
            base64 (Optional[str]): Base64 encoded image data.
            model (Optional[str]): Recognition model to use, defaults to None.
                Available models: 'anime_model_lovelive', 'pre_stable', 'anime', 'full_game_model_kira'.
            **kwargs (Any): Additional arguments passed to the request.

        Returns:
            AnimeTraceResponse: An object containing:
                - Detected characters with their source works
                - Bounding box coordinates
                - Additional metadata (trace_id, AI detection flag)

        Raises:
            ValueError: If none of `url`, `file`, or `base64` is provided.

        Note:
            - Only one of `url`, `file`, or `base64` should be provided.
            - URL and base64 searches use JSON POST requests.
            - File uploads use multipart/form-data POST requests.
        """
        params: dict[str, Any] = {}
        if self.is_multi:
            params["is_multi"] = self.is_multi
        if self.ai_detect:
            params["ai_detect"] = self.ai_detect
        if model:
            params["model"] = model

        if url:
            data = {"url": url, **params}
            resp = await self._send_request(
                method="post",
                json=data,
            )
        elif file:
            files = {"file": read_file(file)}
            resp = await self._send_request(
                method="post",
                files=files,
                data=params or None,
            )
        elif base64:
            data = {"base64": base64, **params}
            resp = await self._send_request(
                method="post",
                json=data,
            )
        else:
            raise ValueError("One of 'url', 'file', or 'base64' must be provided")

        return AnimeTraceResponse(json_loads(resp.text), resp.url)

Attributes

ai_detect = ai_detect instance-attribute
is_multi = is_multi instance-attribute

Functions

__init__(base_url='https://api.animetrace.com', endpoint='v1/search', is_multi=None, ai_detect=None, **request_kwargs)

Initializes an AnimeTrace API client with specified configurations.

Parameters:

Name Type Description Default
base_url str

The base URL for AnimeTrace API, defaults to 'https://api.animetrace.com'.

 'https://api.animetrace.com'
endpoint str

The endpoint for AnimeTrace API, defaults to 'v1/search'.

 'v1/search'
is_multi Optional[int]

Whether to show multiple results, 0 or 1, defaults to None.

 None
ai_detect Optional[int]

Whether to enable AI image detection, 1 for yes, 2 for no, defaults to None.

 None
**request_kwargs Any

Additional arguments passed to the HTTP client.

 {}
Source code in PicImageSearch/engines/anime_trace.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def __init__(
    self,
    base_url: str = "https://api.animetrace.com",
    endpoint: str = "v1/search",
    is_multi: Optional[int] = None,
    ai_detect: Optional[int] = None,
    **request_kwargs: Any,
):
    """Initializes an AnimeTrace API client with specified configurations.

    Args:
        base_url (str): The base URL for AnimeTrace API, defaults to 'https://api.animetrace.com'.
        endpoint (str): The endpoint for AnimeTrace API, defaults to 'v1/search'.
        is_multi (Optional[int]): Whether to show multiple results, 0 or 1, defaults to None.
        ai_detect (Optional[int]): Whether to enable AI image detection, 1 for yes, 2 for no, defaults to None.
        **request_kwargs (Any): Additional arguments passed to the HTTP client.
    """
    base_url = f"{base_url}/{endpoint}"
    super().__init__(base_url, **request_kwargs)
    self.is_multi: Optional[int] = is_multi
    self.ai_detect: Optional[int] = ai_detect
search(url=None, file=None, base64=None, model=None, **kwargs) async

Performs an anime character recognition search on AnimeTrace.

This method supports three ways of searching
  1. Search by image URL
  2. Search by uploading a local image file
  3. Search by providing a base64 encoded image

Parameters:

Name Type Description Default
url Optional[str]

URL of the image to search.

 None
file Union[str, bytes, Path, None]

Local image file, can be a path string, bytes data, or Path object.

 None
base64 Optional[str]

Base64 encoded image data.

 None
model Optional[str]

Recognition model to use, defaults to None. Available models: 'anime_model_lovelive', 'pre_stable', 'anime', 'full_game_model_kira'.

 None
**kwargs Any

Additional arguments passed to the request.

 {}

Returns:

Name Type Description
AnimeTraceResponse AnimeTraceResponse

An object containing: - Detected characters with their source works - Bounding box coordinates - Additional metadata (trace_id, AI detection flag)

Raises:

Type Description
ValueError

If none of url, file, or base64 is provided.
Note
  • Only one of url, file, or base64 should be provided.
  • URL and base64 searches use JSON POST requests.
  • File uploads use multipart/form-data POST requests.
Source code in PicImageSearch/engines/anime_trace.py 
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
@override
async def search(
    self,
    url: Optional[str] = None,
    file: Union[str, bytes, Path, None] = None,
    base64: Optional[str] = None,
    model: Optional[str] = None,
    **kwargs: Any,
) -> AnimeTraceResponse:
    """Performs an anime character recognition search on AnimeTrace.

    This method supports three ways of searching:
        1. Search by image URL
        2. Search by uploading a local image file
        3. Search by providing a base64 encoded image

    Args:
        url (Optional[str]): URL of the image to search.
        file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
        base64 (Optional[str]): Base64 encoded image data.
        model (Optional[str]): Recognition model to use, defaults to None.
            Available models: 'anime_model_lovelive', 'pre_stable', 'anime', 'full_game_model_kira'.
        **kwargs (Any): Additional arguments passed to the request.

    Returns:
        AnimeTraceResponse: An object containing:
            - Detected characters with their source works
            - Bounding box coordinates
            - Additional metadata (trace_id, AI detection flag)

    Raises:
        ValueError: If none of `url`, `file`, or `base64` is provided.

    Note:
        - Only one of `url`, `file`, or `base64` should be provided.
        - URL and base64 searches use JSON POST requests.
        - File uploads use multipart/form-data POST requests.
    """
    params: dict[str, Any] = {}
    if self.is_multi:
        params["is_multi"] = self.is_multi
    if self.ai_detect:
        params["ai_detect"] = self.ai_detect
    if model:
        params["model"] = model

    if url:
        data = {"url": url, **params}
        resp = await self._send_request(
            method="post",
            json=data,
        )
    elif file:
        files = {"file": read_file(file)}
        resp = await self._send_request(
            method="post",
            files=files,
            data=params or None,
        )
    elif base64:
        data = {"base64": base64, **params}
        resp = await self._send_request(
            method="post",
            json=data,
        )
    else:
        raise ValueError("One of 'url', 'file', or 'base64' must be provided")

    return AnimeTraceResponse(json_loads(resp.text), resp.url)

Functions