aimage-sdk 0.1.1

Python SDK for the AI-Mage Search public API

aimage-sdk

Python SDK for the AI-Mage Search public API (/v0). Python 3.12+, httpx is the only dependency.

Install

pip install aimage-sdk
# or: uv add aimage-sdk

Quickstart

import os

from aimage_sdk import AimageClient

client = AimageClient(
    api_key=os.environ["AIMAGE_API_KEY"],  # "aimage_api_..."
    base_url="https://api.search.ai-mage.jp",  # API server origin; the client calls {base_url}/v0/...
)

# Discover accessible projects.
me = client.me()
project_id = me["projects"][0]["id"]

# Upload a video: mints a presigned URL, PUTs the bytes, registers the video.
video = client.upload_video(
    project_id=project_id,
    file="./episode-01.mp4",  # str | pathlib.Path | bytes (bytes need file_name=)
    name="Episode 1",
    season=1,
    episode=1,
    on_progress=print,
)

# Wait until clip extraction and AI tagging finish.
processed = client.wait_for_processing(video["id"], poll_interval_s=10, timeout_s=1800)
if processed["processing_status"] == "failed":
    raise RuntimeError(processed["processing_error"])

# Search clips with a natural-language query.
result = client.search_clips(project_id=project_id, query="two characters arguing in the rain")
for clip in result["clips"]:
    print(clip["start_time"], clip["subtitle"], clip["tags"], clip["characters"])

API surface

• ping() / me()
• mint_upload_url(project_id=, file_name=, content_type=)
• register_video(project_id=, name=, file_name=|s3_key=, season=, episode=, auto_process=)
• get_video(video_id) / list_videos(project_id=, page=, page_size=) / delete_video(video_id)
• search_clips(project_id=, query=, page=, page_size=)
• upload_video(project_id=, file=, name=, ...) — full 3-step upload orchestration
• wait_for_processing(video_id, poll_interval_s=, timeout_s=)

Failed API calls raise AimageApiError with code, message, and HTTP status parsed from the {"error": {"code", "message"}} envelope.

Development

cd sdks/python
uv sync
uv run pytest
uv run ruff check .