e621

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.

Installation

pip install e621-stable

Quickstart

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.

Creating the api client

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"))

Searching

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)

Accessing Attributes

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)

Getting

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")

Updating

api.posts.update(3291457, tag_string_diff="canine -male", description="Rick roll?")

Creating

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?"
)

Hmiku8338/e621