コンテンツにスキップ

IQDB

Classes

Iqdb

Bases: BaseSearchEngine[IqdbResponse]

API client for the Iqdb image search engine.

A client implementation for performing reverse image searches using Iqdb's services. Supports both anime-style images (iqdb.org) and real-life images (3d.iqdb.org).

Attributes:

Name Type Description
base_url str

The base URL for Iqdb searches, determined by is_3d parameter.
Note
  • For anime/artwork images, uses iqdb.org
  • For real-life/3D images, uses 3d.iqdb.org
Source code in PicImageSearch/engines/iqdb.py 
 9
10
11
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
class Iqdb(BaseSearchEngine[IqdbResponse]):
    """API client for the Iqdb image search engine.

    A client implementation for performing reverse image searches using Iqdb's services.
    Supports both anime-style images (iqdb.org) and real-life images (3d.iqdb.org).

    Attributes:
        base_url (str): The base URL for Iqdb searches, determined by is_3d parameter.

    Note:
        - For anime/artwork images, uses iqdb.org
        - For real-life/3D images, uses 3d.iqdb.org
    """

    def __init__(
        self,
        is_3d: bool = False,
        **request_kwargs: Any,
    ):
        """Initializes an Iqdb API client with request configuration.

        Args:
            is_3d (bool): If True, searches on 3d.iqdb.org for real-life images; otherwise, iqdb.org for anime images.
            **request_kwargs (Any): Additional arguments for network requests.
        """
        base_url = "https://3d.iqdb.org" if is_3d else "https://iqdb.org"
        super().__init__(base_url, **request_kwargs)

    async def search(
        self,
        url: Optional[str] = None,
        file: Union[str, bytes, Path, None] = None,
        force_gray: bool = False,
        **kwargs: Any,
    ) -> IqdbResponse:
        """Performs a reverse image search on Iqdb.

        This method supports two ways of searching:
            1. Search by image URL
            2. Search by uploading a local image file

        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.
            force_gray (bool): If True, ignores color information during search, useful for
                    finding similar images with different color schemes.
            **kwargs (Any): Additional arguments passed to the parent class.

        Returns:
            IqdbResponse: An object containing:
                - Search results from various supported image databases
                - Additional metadata about the search
                - The final search URL

        Raises:
            ValueError: If neither `url` nor `file` is provided.

        Note:
            - Only one of `url` or `file` should be provided.
            - The search behavior differs based on the is_3d parameter set during initialization:
                - is_3d=False: Searches anime/artwork images on iqdb.org
                - is_3d=True: Searches real-life images on 3d.iqdb.org
            - The force_gray option can help find visually similar images regardless of coloring
        """
        self._validate_args(url, file)

        data: dict[str, Any] = {}
        files: Optional[dict[str, Any]] = None

        if force_gray:
            data["forcegray"] = "on"

        if url:
            data["url"] = url
        elif file:
            files = {"file": read_file(file)}

        resp = await self._make_request(
            method="post",
            data=data,
            files=files,
        )

        return IqdbResponse(resp.text, resp.url)

Functions

__init__(is_3d=False, **request_kwargs)

Initializes an Iqdb API client with request configuration.

Parameters:

Name Type Description Default
is_3d bool

If True, searches on 3d.iqdb.org for real-life images; otherwise, iqdb.org for anime images.

 False
**request_kwargs Any

Additional arguments for network requests.

 {}
Source code in PicImageSearch/engines/iqdb.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
def __init__(
    self,
    is_3d: bool = False,
    **request_kwargs: Any,
):
    """Initializes an Iqdb API client with request configuration.

    Args:
        is_3d (bool): If True, searches on 3d.iqdb.org for real-life images; otherwise, iqdb.org for anime images.
        **request_kwargs (Any): Additional arguments for network requests.
    """
    base_url = "https://3d.iqdb.org" if is_3d else "https://iqdb.org"
    super().__init__(base_url, **request_kwargs)
search(url=None, file=None, force_gray=False, **kwargs) async

Performs a reverse image search on Iqdb.

This method supports two ways of searching
  1. Search by image URL
  2. Search by uploading a local image file

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
force_gray bool

If True, ignores color information during search, useful for finding similar images with different color schemes.

 False
**kwargs Any

Additional arguments passed to the parent class.

 {}

Returns:

Name Type Description
IqdbResponse IqdbResponse

An object containing: - Search results from various supported image databases - Additional metadata about the search - The final search URL

Raises:

Type Description
ValueError

If neither url nor file is provided.
Note
  • Only one of url or file should be provided.
  • The search behavior differs based on the is_3d parameter set during initialization:
    • is_3d=False: Searches anime/artwork images on iqdb.org
    • is_3d=True: Searches real-life images on 3d.iqdb.org
  • The force_gray option can help find visually similar images regardless of coloring
Source code in PicImageSearch/engines/iqdb.py 
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
async def search(
    self,
    url: Optional[str] = None,
    file: Union[str, bytes, Path, None] = None,
    force_gray: bool = False,
    **kwargs: Any,
) -> IqdbResponse:
    """Performs a reverse image search on Iqdb.

    This method supports two ways of searching:
        1. Search by image URL
        2. Search by uploading a local image file

    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.
        force_gray (bool): If True, ignores color information during search, useful for
                finding similar images with different color schemes.
        **kwargs (Any): Additional arguments passed to the parent class.

    Returns:
        IqdbResponse: An object containing:
            - Search results from various supported image databases
            - Additional metadata about the search
            - The final search URL

    Raises:
        ValueError: If neither `url` nor `file` is provided.

    Note:
        - Only one of `url` or `file` should be provided.
        - The search behavior differs based on the is_3d parameter set during initialization:
            - is_3d=False: Searches anime/artwork images on iqdb.org
            - is_3d=True: Searches real-life images on 3d.iqdb.org
        - The force_gray option can help find visually similar images regardless of coloring
    """
    self._validate_args(url, file)

    data: dict[str, Any] = {}
    files: Optional[dict[str, Any]] = None

    if force_gray:
        data["forcegray"] = "on"

    if url:
        data["url"] = url
    elif file:
        files = {"file": read_file(file)}

    resp = await self._make_request(
        method="post",
        data=data,
        files=files,
    )

    return IqdbResponse(resp.text, resp.url)

Functions