# Waifu.im

> Pull anime artwork into a workflow from Waifu.im, an archive of around 4,300 illustrations tagged by character, series and theme. Get a random image for a daily post or a header, search the archive by tag, shape and pixel size, and read the artist credits and original source that an attribution line needs. Browsing needs no account. Adding an API key also lets a workflow keep albums of its own and report an image to the moderators. Most of this archive is adult material, so every action defaults to safe images only, as the API itself does, and returning adult content is a setting you have to turn on deliberately.

App · Images & Design · 15 actions. Web page: https://docs.lodol.com/docs/integrations/waifu-im

## Actions

### Add an image to an album

This works on your own Waifu.im account, so it needs an API key on the connection. Browsing the archive needs none. Put an image into one of your albums. The image id comes from any of the image actions, so a workflow can search, pick and file in one run.

**Inputs**

- Album (`album_id`, number, required): The album's id, as returned by 'List albums'. At least 1.
- Image (`image_id`, number, required): The image's id, as returned by any of the image actions. At least 1.
- Account (`account_id`, number): Whose albums to work with. Leave blank for the account the API key belongs to, which is almost always what you want. At least 1.

**Outputs**

- `added` (true/false): True when Waifu.im confirmed it
- `album_id` (number): The album it went into
- `image_id` (number): The image that was added
- `user_id` (number): Whose album it is

**Example output**

```json
{
  "added": true,
  "album_id": 7,
  "image_id": 6738,
  "user_id": 42
}
```

### Create an album

This works on your own Waifu.im account, so it needs an API key on the connection. Browsing the archive needs none. Make a new album on the account. Pair it with 'Add an image to an album' to have a workflow build a collection of its own: a week's picks, everything matching a tag, whatever somebody reacted to in chat.

**Inputs**

- Name (`name`, text, required): What to call the album.
- Description (`description`, text): An optional note about what the album is for.
- Account (`account_id`, number): Whose albums to work with. Leave blank for the account the API key belongs to, which is almost always what you want. At least 1.

**Outputs**

- `created_at` (text): When it was made
- `description` (text): Its description
- `id` (number): The new album's id
- `name` (text): Its name
- `user_id` (number): Whose album it is

**Example output**

```json
{
  "created_at": "2026-09-17T10:00:00Z",
  "description": "notes",
  "id": 7,
  "image_count": 2,
  "name": "Created",
  "owner_id": 42,
  "updated_at": null,
  "user_id": 42
}
```

### Get a random image

Pull one anime illustration at random out of Waifu.im's archive, narrowed by tag, shape or size. The usual way to use it: a daily post, a random header, a bit of decoration in a digest. Safe images only unless you change the adult setting, which is how the API behaves too. The response carries the artist credits and the original source, which is what an attribution line needs.

**Inputs**

- Tags (`tags`, text): Only return images carrying all of these tags. Adding a second tag narrows the search rather than widening it. Pick from the list or type any tag the archive has; 'List tags' returns every one with its own description. One or more of: `waifu`, `uniform`, `maid`, `selfies`, `genshin-impact` (Genshin Impact), `raiden-shogun` (Raiden Shogun), `kamisato-ayaka` (Kamisato Ayaka), `marin-kitagawa` (Marin Kitagawa), `mori-calliope` (Mori Calliope), `rem`, `nami`, `one-piece` (One Piece).
- Excluded tags (`excluded_tags`, text): Leave out any image carrying one of these tags. Useful for trimming a theme you do not want even within the safe set. One or more of: `waifu`, `uniform`, `maid`, `selfies`, `genshin-impact` (Genshin Impact), `raiden-shogun` (Raiden Shogun), `kamisato-ayaka` (Kamisato Ayaka), `marin-kitagawa` (Marin Kitagawa), `mori-calliope` (Mori Calliope), `rem`, `nami`, `one-piece` (One Piece).
- Adult content (`is_nsfw`, text): Whether to include images Waifu.im flags as adult. Defaults to 'Safe only', which is also the API's own default. Most of this archive is adult, so the other settings change the result substantially. Waifu.im restricts adult content to users who are 18 or over, so only turn this on where that holds. One of: `False` (Safe only), `True` (Adult only), `All` (Both safe and adult). Default: `False`.
- Orientation (`orientation`, text): Only return images of this shape. Useful when the picture has to fit a banner or a phone screen. One of: `All` (Any shape), `Landscape` (Landscape (wider than tall)), `Portrait` (Portrait (taller than wide)), `Square`. Default: `All`.
- Animated (`is_animated`, text): Whether to return animated images. Defaults to both. The archive holds only a handful of animations, so asking for them alone narrows it a long way. One of: `All` (Both), `True` (Animated only), `False` (Still images only). Default: `All`.
- Width (`width`, text): Filter on pixel width. Write a number, or a comparison such as '>=1920' for at least 1920 pixels across.
- Height (`height`, text): Filter on pixel height. Write a number, or a comparison such as '>=1080'.

**Outputs**

- `artists` (list): Credited artists and their links
- `byte_size` (number): File size in bytes
- `dominant_color` (text): Main colour as a hex code
- `extension` (text): File extension, e.g. '.jpeg'
- `favorites` (number): How many people have favourited it
- `height` (number): Height in pixels
- `id` (number): The image's id
- `is_animated` (true/false): Whether it is animated
- `is_nsfw` (true/false): Whether Waifu.im flags it as adult
- `source` (text): Where the image came from, for an attribution line
- `tag_slugs` (list): Just the tag slugs
- `tags` (list): Tags with their names
- `uploaded_at` (text): When it was added
- `url` (text): Direct link to the image file
- `width` (number): Width in pixels

**Example output**

```json
{
  "artists": [
    {
      "id": 911,
      "name": "Matsogum",
      "patreon": null,
      "pixiv": "https://www.pixiv.net/users/62530933",
      "twitter": "https://twitter.com/Matsogm_"
    }
  ],
  "byte_size": 13739852,
  "dominant_color": "#A6A0A5",
  "extension": ".png",
  "favorites": 4,
  "height": 4852,
  "id": 7811,
  "is_animated": false,
  "is_nsfw": false,
  "preview_url": "https://cdn.waifu.im/7811.png",
  "source": "https://www.pixiv.net/en/artworks/101015206",
  "tag_slugs": [
    "uniform",
    "waifu"
  ],
  "tags": [
    {
      "name": "Uniform",
      "slug": "uniform"
    },
    {
      "name": "Waifu",
      "slug": "waifu"
    }
  ],
  "uploaded_at": "2022-09-05T23:19:51.846633Z",
  "url": "https://cdn.waifu.im/7811.png",
  "width": 2500
}
```

### Get a tag

Look up one tag by its slug and read what it covers. Use it to check a tag before a workflow relies on it, or to show somebody what they are about to subscribe to.

**Inputs**

- Tag (`tag`, text, required): The tag's slug, for example 'waifu' or 'genshin-impact'. 'List tags' returns every one.

**Outputs**

- `description` (text): What the tag covers
- `id` (number): The tag's id
- `image_count` (number): How many images carry it
- `name` (text): Readable name
- `slug` (text): The name to pass to the image actions

**Example output**

```json
{
  "description": "A female anime/manga character.",
  "id": 12,
  "image_count": 0,
  "name": "Waifu",
  "slug": "waifu"
}
```

### Get an album

This works on your own Waifu.im account, so it needs an API key on the connection. Browsing the archive needs none. Read one album and the images in it, in one step. Use it to turn a collection into a post, a slideshow or a digest without having to list the album and then fetch its contents separately.

**Inputs**

- Album (`album_id`, number, required): The album's id, as returned by 'List albums'. At least 1.
- Account (`account_id`, number): Whose albums to work with. Leave blank for the account the API key belongs to, which is almost always what you want. At least 1.
- Page (`page`, number): Which page of results to return, counting from 1. From 1 to 100000. Default: `1`.
- How many to return (`size`, number): How many rows to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.

**Outputs**

- `count` (number): How many rows came back
- `description` (text): Its description
- `has_next_page` (true/false): Whether another page follows
- `id` (number): The album's id
- `image_count` (number): How many images are in it
- `images` (list)
- `name` (text): Its name
- `page` (number): Which page this is
- `total` (number): How many match in total
- `total_pages` (number): How many pages there are
- `user_id` (number): Whose album it is

**Example output**

```json
{
  "count": 1,
  "created_at": "2026-09-17T10:00:00Z",
  "description": "notes",
  "has_next_page": false,
  "id": 7,
  "image_count": 2,
  "images": [
    {
      "artists": [],
      "byte_size": 1146278,
      "dominant_color": "#AC9096",
      "extension": ".jpeg",
      "favorites": 5,
      "height": 850,
      "id": 6738,
      "is_animated": false,
      "is_nsfw": false,
      "preview_url": "https://cdn.waifu.im/6738.jpeg",
      "source": "https://reddit.com/x/",
      "tag_slugs": [
        "waifu"
      ],
      "tags": [
        {
          "name": "Waifu",
          "slug": "waifu"
        }
      ],
      "uploaded_at": null,
      "url": "https://cdn.waifu.im/6738.jpeg",
      "width": 1200
    }
  ],
  "name": "My album",
  "owner_id": 42,
  "page": 1,
  "total": 1,
  "total_pages": 1,
  "updated_at": null,
  "user_id": 42
}
```

### Get an artist

Look up one artist by id or by name and get the links to wherever they publish. Use it after an image action to turn the credit on a picture into a proper attribution with somewhere to point at.

**Inputs**

- Artist (`artist`, text, required): The artist's id, or their name. Ids come back on every image that credits somebody.

**Outputs**

- `deviant_art` (text): Their DeviantArt, if they have one
- `id` (number): The artist's id
- `image_count` (number): How many of their images are held
- `name` (text): Their name
- `patreon` (text): Their Patreon, if they have one
- `pixiv` (text): Their Pixiv, if they have one
- `twitter` (text): Their Twitter, if they have one

**Example output**

```json
{
  "deviant_art": null,
  "id": 2568,
  "image_count": 0,
  "name": "Zelgius AI Art",
  "patreon": "https://www.patreon.com/cw/ZelgiusAI",
  "pixiv": null,
  "twitter": null
}
```

### Get an image

Look up one image by its id and get everything the archive holds on it: the file link and dimensions, its tags, the artists credited for it, where it was sourced from, and whether it is flagged adult. Use it to re-read an image a previous step or an earlier run returned.

**Inputs**

- Image (`image_id`, number, required): The image's id, as returned by any of the image actions. At least 1.

**Outputs**

- `artists` (list): Credited artists and their links
- `byte_size` (number): File size in bytes
- `dominant_color` (text): Main colour as a hex code
- `extension` (text): File extension, e.g. '.jpeg'
- `favorites` (number): How many people have favourited it
- `height` (number): Height in pixels
- `id` (number): The image's id
- `is_animated` (true/false): Whether it is animated
- `is_nsfw` (true/false): Whether Waifu.im flags it as adult
- `source` (text): Where the image came from, for an attribution line
- `tag_slugs` (list): Just the tag slugs
- `tags` (list): Tags with their names
- `uploaded_at` (text): When it was added
- `url` (text): Direct link to the image file
- `width` (number): Width in pixels

**Example output**

```json
{
  "artists": [],
  "byte_size": 1146278,
  "dominant_color": "#AC9096",
  "extension": ".jpeg",
  "favorites": 5,
  "height": 850,
  "id": 6738,
  "is_animated": false,
  "is_nsfw": false,
  "preview_url": "https://cdn.waifu.im/6738.jpeg",
  "source": "https://reddit.com/ptcaas/",
  "tag_slugs": [
    "waifu"
  ],
  "tags": [
    {
      "name": "Waifu",
      "slug": "waifu"
    }
  ],
  "uploaded_at": "2021-11-02T11:16:19.048684Z",
  "url": "https://cdn.waifu.im/6738.jpeg",
  "width": 1200
}
```

### Get archive statistics

Read Waifu.im's public totals: how many images, tags and artists it holds and how many requests it has served. Useful as a health check at the top of a longer workflow, and for a sense of how big the archive is before pointing something at it.

**Inputs**: None.

**Outputs**

- `reachable` (true/false): True when the API answered
- `total_artists` (number): Artists credited
- `total_images` (number): Images in the archive
- `total_requests` (number): Requests the API has served
- `total_tags` (number): Tags available

**Example output**

```json
{
  "reachable": true,
  "total_artists": 568,
  "total_favorites": null,
  "total_images": 4289,
  "total_requests": 124882792,
  "total_tags": 20,
  "total_users": null
}
```

### Get your profile

This works on your own Waifu.im account, so it needs an API key on the connection. Browsing the archive needs none. Read the Waifu.im account the connected key belongs to: its id, display name and role. Mostly useful as a check that the key works and is pointing at the account you meant, and for the user id the album actions are addressed by.

**Inputs**: None.

**Outputs**

- `created_at` (text): When the account was made
- `id` (number): Your Waifu.im user id
- `is_banned` (true/false): Whether the account is banned
- `name` (text): Your display name
- `role` (text): Your role on the site

**Example output**

```json
{
  "created_at": null,
  "id": 42,
  "is_banned": null,
  "name": "tester",
  "role": "User"
}
```

### List albums

This works on your own Waifu.im account, so it needs an API key on the connection. Browsing the archive needs none. List the albums on the account, which is how Waifu.im lets somebody keep collections of images. Use it to find the album to add to, or to read back a collection a workflow has been building up.

**Inputs**

- Account (`account_id`, number): Whose albums to work with. Leave blank for the account the API key belongs to, which is almost always what you want. At least 1.
- Page (`page`, number): Which page of results to return, counting from 1. From 1 to 100000. Default: `1`.
- How many to return (`size`, number): How many rows to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.

**Outputs**

- `albums` (list)
- `count` (number): How many rows came back
- `has_next_page` (true/false): Whether another page follows
- `page` (number): Which page this is
- `total` (number): How many match in total
- `total_pages` (number): How many pages there are
- `user_id` (number): Whose albums these are

**Example output**

```json
{
  "albums": [
    {
      "created_at": "2026-09-17T10:00:00Z",
      "description": "notes",
      "id": 7,
      "image_count": 2,
      "name": "My album",
      "owner_id": 42,
      "updated_at": null
    }
  ],
  "count": 1,
  "has_next_page": false,
  "page": 1,
  "total": 1,
  "total_pages": 1,
  "user_id": 42
}
```

### List artists

List the artists whose work is in the archive, with links to wherever they publish: Patreon, Pixiv, Twitter, DeviantArt. Search by name to find one in particular. Use it to credit properly, or to follow the person behind a picture you liked.

**Inputs**

- Name contains (`name`, text): Only return artists whose name matches. Leave blank for all.
- Page (`page`, number): Which page of results to return, counting from 1. From 1 to 100000. Default: `1`.
- How many to return (`size`, number): How many rows to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.

**Outputs**

- `artists` (list)
- `count` (number): How many rows came back
- `has_next_page` (true/false): Whether another page follows
- `page` (number): Which page this is
- `total` (number): How many match in total
- `total_pages` (number): How many pages there are

**Example output**

```json
{
  "artists": [
    {
      "deviant_art": null,
      "id": 2568,
      "image_count": 28,
      "name": "Zelgius AI Art",
      "patreon": "https://www.patreon.com/cw/ZelgiusAI",
      "pixiv": null,
      "twitter": null
    },
    {
      "deviant_art": null,
      "id": 80,
      "image_count": 23,
      "name": "GongHa",
      "patreon": null,
      "pixiv": "https://www.pixiv.net/users/11525425",
      "twitter": "https://twitter.com/gongha1020"
    }
  ],
  "count": 2,
  "has_next_page": true,
  "page": 1,
  "total": 568,
  "total_pages": 284
}
```

### List tags

List every tag the archive files images under, each with its own description. Worth running before a search: the list is short, and several of the tags describe explicit sexual content, so this is how to see exactly what a tag covers before pointing a workflow at it.

**Inputs**

- Page (`page`, number): Which page of results to return, counting from 1. From 1 to 100000. Default: `1`.
- How many to return (`size`, number): How many rows to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.

**Outputs**

- `count` (number): How many rows came back
- `has_next_page` (true/false): Whether another page follows
- `page` (number): Which page this is
- `tags` (list)
- `total` (number): How many match in total
- `total_pages` (number): How many pages there are

**Example output**

```json
{
  "count": 3,
  "has_next_page": true,
  "page": 1,
  "tags": [
    {
      "description": "A female anime/manga character.",
      "id": 12,
      "image_count": 4278,
      "name": "Waifu",
      "slug": "waifu"
    },
    {
      "description": "Any kind of erotic content, basically any nsfw image.",
      "id": 3,
      "image_count": 3014,
      "name": "Ero",
      "slug": "ero"
    }
  ],
  "total": 20,
  "total_pages": 7
}
```

### Remove an image from an album

This works on your own Waifu.im account, so it needs an API key on the connection. Browsing the archive needs none. Take an image back out of one of your albums. This only changes the album; the image stays in the archive.

**Inputs**

- Album (`album_id`, number, required): The album's id, as returned by 'List albums'. At least 1.
- Image (`image_id`, number, required): The image's id, as returned by any of the image actions. At least 1.
- Account (`account_id`, number): Whose albums to work with. Leave blank for the account the API key belongs to, which is almost always what you want. At least 1.

**Outputs**

- `album_id` (number): The album it came out of
- `image_id` (number): The image that was removed
- `removed` (true/false): True when Waifu.im confirmed it
- `user_id` (number): Whose album it is

**Example output**

```json
{
  "album_id": 7,
  "image_id": 6738,
  "removed": true,
  "user_id": 42
}
```

### Report an image

This works on your own Waifu.im account, so it needs an API key on the connection. Browsing the archive needs none. Report an image to the Waifu.im moderators. The archive is contributed by its users and its operators host rather than vet every upload, so this is the route for anything that should not be there: a picture tagged wrongly, a copyright complaint from the artist, or something worse. Worth wiring up if a workflow puts these images in front of other people.

**Inputs**

- Image (`image_id`, number, required): The image's id, as returned by any of the image actions. At least 1.
- What is wrong with it (`description`, text): Why it is being reported. Say as much as you can: the moderators act on this by hand.

**Outputs**

- `created_at` (text): When it was filed
- `description` (text): What was said about it
- `image_id` (number): The image that was reported
- `report_id` (number): The report's id
- `reported` (true/false): True when Waifu.im accepted the report
- `status` (text): Where the report stands, e.g. 'Pending'

**Example output**

```json
{
  "created_at": "2026-09-17T10:00:00Z",
  "description": "wrong tag",
  "image_id": 6738,
  "report_id": 99,
  "reported": true,
  "status": "Pending"
}
```

### Search images

Search the archive and get a page of matching images, with every filter the API offers: tags to include and exclude, artist, orientation, pixel size, animation, and how to order the results. Use it to build a gallery, pick a set of wallpapers, or page through everything carrying a tag. Safe images only unless you change the adult setting.

**Inputs**

- Tags (`tags`, text): Only return images carrying all of these tags. Adding a second tag narrows the search rather than widening it. Pick from the list or type any tag the archive has; 'List tags' returns every one with its own description. One or more of: `waifu`, `uniform`, `maid`, `selfies`, `genshin-impact` (Genshin Impact), `raiden-shogun` (Raiden Shogun), `kamisato-ayaka` (Kamisato Ayaka), `marin-kitagawa` (Marin Kitagawa), `mori-calliope` (Mori Calliope), `rem`, `nami`, `one-piece` (One Piece).
- Excluded tags (`excluded_tags`, text): Leave out any image carrying one of these tags. Useful for trimming a theme you do not want even within the safe set. One or more of: `waifu`, `uniform`, `maid`, `selfies`, `genshin-impact` (Genshin Impact), `raiden-shogun` (Raiden Shogun), `kamisato-ayaka` (Kamisato Ayaka), `marin-kitagawa` (Marin Kitagawa), `mori-calliope` (Mori Calliope), `rem`, `nami`, `one-piece` (One Piece).
- Adult content (`is_nsfw`, text): Whether to include images Waifu.im flags as adult. Defaults to 'Safe only', which is also the API's own default. Most of this archive is adult, so the other settings change the result substantially. Waifu.im restricts adult content to users who are 18 or over, so only turn this on where that holds. One of: `False` (Safe only), `True` (Adult only), `All` (Both safe and adult). Default: `False`.
- Orientation (`orientation`, text): Only return images of this shape. Useful when the picture has to fit a banner or a phone screen. One of: `All` (Any shape), `Landscape` (Landscape (wider than tall)), `Portrait` (Portrait (taller than wide)), `Square`. Default: `All`.
- Animated (`is_animated`, text): Whether to return animated images. Defaults to both. The archive holds only a handful of animations, so asking for them alone narrows it a long way. One of: `All` (Both), `True` (Animated only), `False` (Still images only). Default: `All`.
- Order by (`order_by`, text): How to sort the results. Defaults to random, which is the API's own default, so ask for 'Newest' or 'Most favourited' when you want a stable order. One of: `Random`, `UploadedAt` (Newest first), `Favorites` (Most favourited). Default: `Random`.
- Width (`width`, text): Filter on pixel width. Write a number, or a comparison such as '>=1920' for at least 1920 pixels across.
- Height (`height`, text): Filter on pixel height. Write a number, or a comparison such as '>=1080'.
- Artists (`artists`, text): Only return work by these artists, by id. 'List artists' returns the ids.
- Skip these images (`excluded_ids`, text): Image ids to leave out. Feed back what a previous run returned to avoid repeating yourself.
- Page (`page`, number): Which page of results to return, counting from 1. From 1 to 100000. Default: `1`.
- How many to return (`size`, number): How many rows to return, from 1 to 100. Defaults to 20. From 1 to 100. Default: `20`.

**Outputs**

- `count` (number): How many rows came back
- `has_next_page` (true/false): Whether another page follows
- `images` (list)
- `nsfw_filter` (text): Which way the adult filter was set for this search: 'False' for safe only, 'True' for adult only, 'All' for both
- `page` (number): Which page this is
- `total` (number): How many match in total
- `total_pages` (number): How many pages there are

**Example output**

```json
{
  "count": 2,
  "has_next_page": true,
  "images": [
    {
      "artists": [
        {
          "id": 63,
          "name": "\u3048\u307f\u3087",
          "patreon": null,
          "pixiv": "https://www.pixiv.net/users/5596229",
          "twitter": "https://twitter.com/emyo27"
        }
      ],
      "byte_size": 1209399,
      "dominant_color": "#7F6A71",
      "extension": ".jpg",
      "favorites": 7,
      "height": 1998,
      "id": 7277,
      "is_animated": false,
      "is_nsfw": false,
      "preview_url": "https://cdn.waifu.im/7277.jpg",
      "source": "https://www.pixiv.net/en/artworks/82523051",
      "tag_slugs": [
        "waifu"
      ],
      "tags": [
        {
          "name": "Waifu",
          "slug": "waifu"
        }
      ],
      "uploaded_at": "2021-12-07T20:50:35.233077Z",
      "url": "https://cdn.waifu.im/7277.jpg",
      "width": 1200
    },
    {
      "artists": [
        {
          "id": 1118,
          "name": "\u3046\u306a\u3055\u304b///C102\u65e5\u66dc\u65e5\u897f\u308117b",
          "patreon": null,
          "pixiv": "https://pixiv.net/users/52141",
          "twitter": "https://twitter.com/unasaka0309"
        }
      ],
      "byte_size": 1430746,
      "dominant_color": "#726964",
      "extension": ".jpg",
      "favorites": 3,
      "height": 1414,
      "id": 7285,
      "is_animated": false,
      "is_nsfw": false,
      "preview_url": "https://cdn.waifu.im/7285.jpg",
      "source": "https://twitter.com/unasaka0309/status/1469149552351801345",
      "tag_slugs": [
        "uniform",
        "waifu"
      ],
      "tags": [
        {
          "name": "Uniform",
          "slug": "uniform"
        },
        {
          "name": "Waifu",
          "slug": "waifu"
        }
      ],
      "uploaded_at": "2021-12-10T11:00:16.972096Z",
      "url": "https://cdn.waifu.im/7285.jpg",
      "width": 2000
    }
  ],
  "nsfw_filter": "False",
  "page": 1,
  "total": 1254,
  "total_pages": 627
}
```