Search Client

SearchClient is the ORPC-only client for AI-Mage Search. Every high-level wrapper calls /rpc/<procedure> on the selected backend service.

Creating a Client

from aimage import search
from aimage.search.settings import SearchService

client = search.client(
    token="your_token_here",
    service=SearchService.PROD,
)

You can also create it directly:

from aimage.search.client import SearchClient

client = SearchClient(
    api_key="your_api_key_here",
    service="https://custom-api.example.com",
)

SearchClient accepts token, api_key, base_url, service, timeout, headers, and additional httpx.Client options. api_key takes precedence over token; when neither is passed, the SDK reads AIMAGE_API_KEY and AIMAGE_SEARCH_TOKEN.

service can be SearchService.PROD, SearchService.DEV, SearchService.STAGING, SearchService.LOCAL, or a custom origin URL. Passing base_url overrides service.

Email Login and TOTP

Entering the login context sends the email code. Verify the code after the user receives it:

from aimage.search.client import SearchClient
from aimage.search.settings import SearchService

client = SearchClient(service=SearchService.PROD)

with client.login_with_email(email="[email protected]") as login:
    result = login.code(input("email code> "))

If the backend requires MFA, continue with TOTP or a recovery code:

with client.login_with_email(email="[email protected]") as login:
    login.code(input("email code> "))
    result = login.totp(input("totp> "))

Direct one-shot login is also supported:

client.login_with_email(
    email="[email protected]",
    email_code="123456",
    totp_code="654321",
)

ORPC Calls

All SDK wrappers use ORPC endpoints:

client.rpc("data/characters/list", {"project_id": "..."})

The high-level namespaces mirror the backend router structure:

client.data.characters.list(project_id="...")
client.data.translationTables.list(project_id="...")
client.kensaku.clips.textSearch(project_id="...", query="sunset")
client.kensaku.videos.processedFiles(video_id="...")
client.agent.read.projectContext(project_id="...")

Main namespaces:

Namespace	Scope
client.auth	login, current user, MFA / TOTP
client.data	characters, resources, reference images, translation tables, manga, novels, dynamic tags
client.kensaku	projects, videos, clips, chatbot conversations
client.agent	agent read/write procedures

For write, update, delete, translation table, material, clip metadata, and conversation branch APIs, see CRUD and Updates.

Readable Output

Common models provide compact str() output:

print(project)
print(video)
print(clip)

repr() remains more detailed for debugging.