The open and supported part of the waifu.pics API is incredibly easy to use. You can find detailed information about how to utilize this in your application below.
If you have any issues or questions with the API, please create a GitHub issue.
Note: We have switched the API URL to https://api.waifu.pics from https://waifu.pics/api. While the old route still works, you should switch any existing applications to use the newer URL.
Available Categories
The API provides various image categories in both SFW (Safe for Work) and NSFW (Not Safe for Work) classifications.
SFW Categories
waifu
neko
shinobu
megumin
bully
cuddle
cry
hug
awoo
kiss
lick
pat
smug
bonk
yeet
blush
smile
wave
highfive
handhold
nom
bite
glomp
slap
kill
kick
happy
wink
poke
dance
cringe
NSFW Categories
waifu
neko
trap
blowjob
Endpoints
The API provides two main endpoints for retrieving waifu images.
Get Single Image
Receive one random image URL from your endpoint of choice.
https://api.waifu.pics/type/categoryGET
Parameter
Type
Description
type
string
The type classification. Valid types are "sfw" and "nsfw".
category
string
The category of image to retrieve (see available categories above).
Example Response:
{
"url": "https://i.waifu.pics/Tj6Wzwo.png"
}
Example Usage
To get a random SFW "waifu" image: https://api.waifu.pics/sfw/waifu
Get Multiple Images
Receive 30 unique images from a specific endpoint or category.
https://api.waifu.pics/many/type/categoryPOST
Parameter
Type
Description
type
string
The type classification. Valid types are "sfw" and "nsfw".
category
string
The category of image to retrieve (see available categories above).
Request Body:
Field
Type
Description
exclude
string[]
An array of URLs to exclude from the response (optional).
You can use the "exclude" parameter to avoid getting duplicate images when making multiple requests.
Implementation Examples
Here are some examples of how to use the waifu.pics API in different programming languages.
// Fetch a single image
fetch('https://api.waifu.pics/sfw/waifu')
.then(response => response.json())
.then(data => {
console.log(data.url);
// Use the image URL as needed
})
.catch(error => console.error('Error fetching waifu:', error));
// Fetch multiple images
fetch('https://api.waifu.pics/many/sfw/waifu', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
exclude: []
})
})
.then(response => response.json())
.then(data => {
console.log(data.files);
// Process the array of image URLs
})
.catch(error => console.error('Error fetching multiple waifus:', error));
import requests
# Fetch a single image
def get_single_waifu(type="sfw", category="waifu"):
response = requests.get(f"https://api.waifu.pics/{type}/{category}")
if response.status_code == 200:
return response.json()["url"]
else:
return f"Error: {response.status_code}"
# Fetch multiple images
def get_multiple_waifus(type="sfw", category="waifu", exclude=[]):
payload = {"exclude": exclude}
response = requests.post(
f"https://api.waifu.pics/many/{type}/{category}",
json=payload
)
if response.status_code == 200:
return response.json()["files"]
else:
return f"Error: {response.status_code}"
# Example usage
single_image = get_single_waifu()
print(f"Single image: {single_image}")
multiple_images = get_multiple_waifus()
print(f"Received {len(multiple_images)} images")
for img in multiple_images[:3]:
print(img) # Print the first 3 images
Best Practices
Use caching for frequently used images to reduce API calls
Implement error handling in your applications
Consider rate limiting your requests to avoid overloading the servers
For NSFW content, ensure your application has proper age verification
Custom Sources
Create and use your own image collections with Waifu Gallery by creating custom source configurations.
What are Custom Sources?
Custom sources allow you to define your own collections of images that can be used with the Waifu Gallery Website. This feature enables you to integrate personal image sets or create specialized categories beyond the default offerings.
Custom sources are defined using a JSON template that specifies categories and image URLs in both SFW (Safe for Work) and NSFW (Not Safe for Work) classifications.
Custom Source Template
To create a custom source, you'll need to follow the JSON template structure below:
Do not change the "sfw", "nsfw" and "sourceInfo" keys in the template. You can leave either section empty (NOT sourceInfo) if you don't have images for that classification (e.g., "sfw": [],), but the keys must remain in the JSON structure.
Field Descriptions
Field
Type
Description
title & category
string
Name of your custom source or category
description & information
string
Optional brief description of your source or category
version
string
Version number for your source template
author
string
Your name or identifier
contact
string
Optional contact information
images
string[]
Array of direct URLs to your images
Implementing Custom Sources
To use custom sources with the Waifu Gallery Website, follow these steps:
Create your JSON template following the structure above or copy the provided template here.
Host your images on a reliable image hosting service
Ensure all image URLs are direct links to the images themselves
Import the file into your applications sidebar and press Import Source
Note
Your imported Sources will be saved in Local Storage. To remove it, either replace it with a different source or press the red X button on the right of the Import button. It will only be clickable if you have contents in your Local Storage
Recommended Image Hosts:
Postimages.org - Allows for bulk copying direct links to images
Imgur - Use direct image links (ending with file extension)
Waifu.pics API: You can Submit your Images here but from my experience the submit Form doesn't work most of the time.
Waifu Gallery Website: Yes, just use a custom source as described here.
What are the rate limits?
The API currently does not have strict rate limits, but we ask that you use it responsibly. If you're making a large number of requests, consider implementing your own rate limiting.
Are there other endpoints for different images?
Currently, the endpoints listed in this documentation are the only supported endpoints. Check the GitHub repository for updates or new features.
Is this site legal outside of planet Earth?
Yes, but only if you have a Martian lawyer to back you up. Otherwise, the interplanetary copyright police might come knocking!