aiotracemoeapi 3.1.1

Async wrapper for Trace.moe API

AioTraceMoeAPI

A simple, but extensible asynchronous Python wrapper for the trace.moe API.

Key Features

• Async: Built on top of httpx for high-performance asynchronous HTTP requests.
• Typed: Fully typed codebase for better developer experience and IDE support.
• Pydantic v2: Uses Pydantic v2 for robust data validation and serialization.

Installation

You can install the package using uv or pip:

uv add aiotracemoeapi

or

pip install aiotracemoeapi

Usage Examples

Basic Search by URL

import asyncio
from aiotracemoeapi import TraceMoe

async def main():
    api = TraceMoe()
    
    # Search by URL
    # Note: is_url=True is required when passing a URL string
    result = await api.search("https://images.plurk.com/32B15UXxymfSMwKGTObY5e.jpg", is_url=True)
    
    if result.result:
        print(f"Anime: {result.result[0].filename}")
        print(f"Similarity: {result.result[0].similarity}")
    else:
        print("No results found.")

if __name__ == "__main__":
    asyncio.run(main())

Running Examples

Examples can be run using uv run:

uv run examples/console.py

Search by File Upload

You can search using a local file path.

import asyncio
from aiotracemoeapi import TraceMoe

async def main():
    api = TraceMoe()
    
    # Search by local file path
    # Ensure 'image.jpg' exists in your directory
    try:
        result = await api.search("image.jpg")
        
        if result.result:
            print(f"Anime: {result.result[0].filename}")
            print(f"Episode: {result.result[0].episode}")
    except FileNotFoundError:
        print("File not found!")

if __name__ == "__main__":
    asyncio.run(main())

Checking Account Status

You can check your API usage limits and quota.

import asyncio
from aiotracemoeapi import TraceMoe

async def main():
    # Initialize with your API token (optional, but recommended for higher limits)
    # Get your token from https://trace.moe/account
    api = TraceMoe(token="your_token_here")
    
    me = await api.me()
    
    print(f"ID: {me.id}")
    print(f"Priority: {me.priority}")
    print(f"Quota Used: {me.quota_used}")
    print(f"Quota Total: {me.quota}")

if __name__ == "__main__":
    asyncio.run(main())