Metadata-Version: 2.5
Name: aimage-sdk
Version: 0.7.0
Summary: Python SDK for the AI-Mage Search public API
Project-URL: Documentation, https://api.search.ai-mage.jp/docs
Project-URL: Repository, https://github.com/aimagexyz/aimage-monorepo
Author: AI-Mage
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.28
Description-Content-Type: text/markdown

# aimage-sdk

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

## Install

```sh
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

```python
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

```sh
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.
