e621 is a feature-rich high-level e621 and e926 API wrapper.
It provides access to almost all of the endpoints available. The only exceptions are unstable and admin-only endpoints.
e621 API documentation is currently highly undocumented, unstable, and sometimes even untruthful. We tried to wrap it in a sanest possible way, properly documenting all the possible ways to interact with it. However, if you still have any questions, bugs to report, or features to request -- please, create an issue on our github page and we will reply as soon as we can.
pip install e621-stable
We translate everything the API returns to python data types created with pydantic. Everything is 100% typehinted so you get autocomplete everywhere and your IDE will warn you if you are sending invalid arguments or using nonexistent attributes.
- To create the most basic client, all you need to do is
from e621 import E621
api = E621()
- If you wish to get information about your account, use your blacklist or create/update/delete any of the e621's entities, you will have to create an api key and put it into the API client as such:
api = E621(("your_e621_login", "your_e621_api_key"))
The majority of the endpoints allow you to query for a list of their entities, be it posts, pools or tags.
- To search for posts that match the "canine" but not the "3d" tag:
posts = api.posts.search("canine -3d")
# Or
posts = api.posts.search(["canine", "-3d"])
- To search for pools whose names start with "hello" and end with "kitty":
posts = api.pools.search(name_matches="hello*kitty")
- e621 searching api is paginated, which means that if you want to get a lot of posts, you will have to make multiple requests with a different "page" parameter. To simplify interactions with paginated queries, all of our searching endpoints support the "limit", "page", and "ignore_pagination" parameters. If you wish to get a specific number of entities, simply pass the "limit" and "ignore_pagination" arguments:
tags = api.tags.search(name_matches="large_*", limit=900, ignore_pagination=True)
When you have retrieved the entities, you can access any of their attributes without dealing with json.
for post in posts:
print(post.score.total, post.all_tags, post.relationships.parent_id)
with open(f"{post.id}.{post.file.ext}", "wb") as f:
f.write(requests.get(post.file.url).content)
Many entities that have unique identifiers (such as post_id or username) support indexing using these ids:
post = api.posts.get(3291457)
posts = api.posts.get([3291457, 3069995])
pool = api.pools.get(28232)
user = api.users.get("fox")
api.posts.update(3291457, tag_string_diff="canine -male", description="Rick roll?")
from pathlib import Path
api.posts.create(
tag_string="canine 3d rick_roll",
file=Path("path/to/rickroll.webm"),
rating="s",
sources=[],
description="Rick roll?"
)