iqdb-client

iqdb.org api client for Node.js.

English | 中文文档

• Feature
• BREAK CHANGES
• Install
• Usage
  • Params
    • services avaliable for iqdb2d (lib='www'):
    • services avaliable for 3diqdb (lib='3d'):
  • Returns
• Advanced Usage
• Support this package
• License

Feature

• Type definitions ready.
• Support 'ignore color'.
• Support searching on single lib (simple search).
• Support both iqdb2d and iqdb3d.
• Support searching by file(buffer or stream) and url
• Based on Fetch

BREAK CHANGES

Since 3.0.0, minimum Nodejs requirement is updated to Node v18, due to a shift from node-fetch to native fetch.

Since 2.0.0, miss typo of word similarity has been fixed, thus corresponding field in your custom IQDBClientConfig should be change. If you are using default config, you are good to go. The type of field similarity in interface IQDBSearchResultItem has been changed from number | string to number | null，meaning it will not fallback to string while parsing failed.

Install

npm install iqdb-client
# or with yarn
yarn add iqdb-client

Usage

const searchPic = require('iqdb-client')
const result = (await searchPic('https://pixiv.cat/84035784-3.jpg', { lib: 'www' }))
/** also support ES Module Import*/

//see ./src/api.test.ts for more examples.
if(result.ok){
    console.log(result.data)
}

Params

searchPic(pic: string | Buffer | Readable, 
{ lib, forcegray, libs,fileName }: IQDB_SEARCH_OPTIONS_ALL)

• lib: string, required 'www'(for iqdb2d) or '3d'(for 3diqdb), or other lib name defined in type IQDB_SEARCH_LIBRARY_2D in h.ts for single-lib search.
• forcegray: boolean, default false whether ignore color.
• fileName: string
  Determines field 'filename' in form data. Only make sense when searching by files. When not provide, a random-summon string will hold the place.
• service: Array<number> Determine services to search on when performing search on multi-service.

services avaliable for iqdb2d (lib='www'):

export enum IQDBLibs_2D {
    danbooru = 1,
    konachan = 2,
    'yande.re' = 3,
    gelbooru = 4,
    'sankaku channel' = 5,
    'e-shuushuu' = 6,
    zerochan = 11,
    'anime-picture' = 13
}

services avaliable for 3diqdb (lib='3d'):

export enum IQDBLibs_3D {
    '3dbooru' = 7,
    'idol' = 9
}

Returns

While successfully request iqdb.org, function will return an object with {ok:boolean}. If similarity check passes, field ok will be set to true. See Example Result While meet exceptions, function will return it in an object as text. For example:

{
    ok:false,
    /*error info*/
    err:'HTTP 400'
}

Exception handle in this package is not mature yet due to lack of real test. Example Result

{
    "ok": true,
    "data": [{
        "head": "Your image",
        "img": "/thu/thu_114514.jpg",
        "name": "84035784_p2.jpg",
        "similarity": null,
        "size": {
            "width": 1703,
            "height": 2459
        },
        "type": null
    }, {
        "head": "Best match",
        "sourceUrl": "//danbooru.donmai.us/posts/4076714",
        "similarity": 0.96,
        "img": "/danbooru/1/f/8/1f8ff3c560a0689e795938138dac7b1f.jpg",
        "size": {
            "width": 1703,
            "height": 2459
        },
        "type": "Safe",
        "source": ["Danbooru", "Gelbooru"]
    }, {
        "head": "Additional match",
        "sourceUrl": "https://yande.re/post/show/678391",
        "similarity": 0.92,
        "img": "/moe.imouto/8/0/1/801df5f665e61e6f87eb85431f2ca2a1.jpg",
        "size": {
            "width": 1703,
            "height": 2459
        },
        "type": "Safe",//shows whether is nsfw, might be one of 'Safe' | 'Ero' | 'Explicit'
        "source": ["yande.re"]
    }],
    "service": [1, 2, 3, 4, 5, 6, 11, 13] //services used in this search
}

Advanced Usage

interface IQDBClientConfig {
    baseDomain: string,
    similarityPass: number
    userAgent: string,
    fetchOptions?: RequestInit
}
const { makeSearchFunc } = require('iqdb-client')
const searchPic = await makeSearchFunc({
            baseDomain: `127.0.0.1`,
            similarityPass: 0.6,
            userAgent: 'testa',
        })

Use makeSearchFunc()to customize config. makeSearchFunc()will return a new searchPic() searchPic() which is default exported by this module uses defaultConfig:

export const defaultConfig: IQDBClientConfig = {
    baseDomain: 'iqdb.org',
    similarityPass: 0.6,
    userAgent: 'node',
}

Support this package

• This package makes sense because of iqdb.org. Support them is supporting the package.
• Open issue or PR for questions.

License

The code contained within this repository is licensed under the MIT License. See LICENSE for more information.