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()
• list_projects()

Videos:

• 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=, processing_status=, order=, page=, page_size=) / delete_video(video_id)
• upload_video(project_id=, file=, name=, ...) — full 3-step upload orchestration
• wait_for_processing(video_id, poll_interval_s=, timeout_s=)

Reference images:

• mint_reference_image_upload_url(project_id=, file_name=, content_type=)
• register_reference_image(project_id=, file_name=|s3_key=, name=, category=, tags=, purpose=, license=, is_searchable=)
• list_reference_images(project_id=, page=, page_size=) / get_reference_image(reference_image_id) / delete_reference_image(reference_image_id)
• upload_reference_image(project_id=, file=, ...) — full 3-step upload orchestration

Materials:

• mint_material_upload_url(project_id=, file_name=, content_type=)
• register_material(project_id=, file_name=|s3_key=, name=, auto_process=)
• list_materials(project_id=, file_type=, material_type=, page=, page_size=) / get_material(material_id) / delete_material(material_id)
• upload_material(project_id=, file=, ...) — full 3-step upload orchestration

Characters and visual assets:

• list_characters(project_id=, page=, page_size=) / get_character(character_id) — characters with their images (stable visual_asset_id + short-lived download_url)
• list_visual_assets(project_id=, source_type=, character_id=, page=, page_size=) / resolve_visual_assets(project_id=, visual_asset_ids=)

Clips and search:

• get_clip(clip_id) / update_clip(clip_id, subtitle=, description=, tags=, character_ids=)
• search_clips(project_id=, query=, reference_image_ids=, image_importance=, page=, page_size=) — pass query and/or reference_image_ids
• search_moments(project_id=, query=, sources=, season=, video_ids=, limit=, offset=) — Alaya moment index (projects whose search_capabilities include moments; 409 MOMENT_INDEX_NOT_AVAILABLE otherwise)

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 .