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

API key permissions

New public API keys default to read_only: search (including POST), listing, fetching, and asset URL resolution remain available. For the upload examples below, explicitly create a read_write key and use a project where the owner has admin access (video writes) or at least editor access (clip updates, reference images, materials). Review upload/check creation also requires read_write and Review membership. Optional expiry is set in the developer settings; expired keys return 401 across SDKs, REST, and MCP. Existing keys retain write access and no expiry during migration. To change permissions or expiry, create a new key, switch consumers, then revoke the old one.

Read-only material fetches return pending for unprocessed files without starting extraction. Existing extracted text remains readable. Read-only refers to customer resource operations; derived read caches and usage records may still be maintained by the service.

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)
• get_video_media(video_id, rendition="playback") — time-limited playback (playback, default) or original (original) URL
• 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; returns ranking (similarity is a 0–1 score only when it is "semantic") and matched_characters (character names recognized in query); reference images must be embedding_status == "ready" (409 REFERENCE_IMAGE_NOT_EMBEDDED otherwise)
• 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)

Mage Review NG check (same key; the key owner must be a reviewer on the Mage Review project's default proposal):

• mint_review_upload_url(project_id=, filename=, file_size=) / run_negative_check(image_id=, template=) / get_negative_check(job_id)
• check_image(project_id=, file=, file_name=, template=) — upload + run in one call
• wait_for_negative_check(job_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 .

Transport security (0.5.0)

Version 0.5.0 introduces breaking transport changes from 0.4.x.

API and presigned upload URLs must use HTTPS and must not contain URL credentials. The client does not follow redirects. For local development only, allow_insecure_localhost=True permits HTTP on localhost, 127.0.0.1, and [::1]; it does not permit remote HTTP servers. Existing HTTP integrations must migrate to HTTPS before upgrading.

The existing timeout option (default 30 seconds) controls httpx network operation timeouts. Python polling timeouts are checked between requests, not a hard wall-clock deadline for in-flight I/O. No requests are automatically retried; a timeout does not guarantee a server-side write was rolled back.