# Agent Media Tools — Python SDK

[![status](https://img.shields.io/badge/status-source%20preview-yellow)](https://agentmediatools.com/integrations)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-green)](https://pypi.org/project/agentmediatools/)

Python client for [Agent Media Tools](https://agentmediatools.com) — a free online platform for image processing, PDF manipulation, web scraping, AI generation, QR codes, pastebin, webhooks, and more.

## Installation

The PyPI package is not published yet. For local review from this repository:

```bash
cd sdk/python
pip install -e .
```

Registry installation instructions will be added after the official package is published.

## Quick Start

### Free tier — no API key needed

```python
from agentmediatools import Client

client = Client()

# 🖼️ Resize an image
with open("photo.jpg", "rb") as f:
    result = client.image.resize(f, width=800, format="webp")
    with open("photo.webp", "wb") as out:
        out.write(result)

# 🔗 Generate a QR code
qr = client.qrcode.generate("https://example.com")
with open("qrcode.png", "wb") as f:
    f.write(qr)

# 📄 Create a paste
paste = client.create_paste("Hello world!", title="My first paste")
print(paste)

# 🛠️ Developer utilities
print(client.dev.uuid())
print(client.dev.ip())
```

### Agent API key — for premium endpoints

```python
from agentmediatools import Client

client = Client(api_key="mt_your_key_here")

# 🌐 Scrape a web page
content = client.scrape("https://example.com")
print(content)

# 📹 Get video metadata
info = client.video_info("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(info)

# 🎞️ Extract audio from a video
audio = client.audio_extract("https://example.com/video.mp4")
with open("audio.mp3", "wb") as f:
    f.write(audio)
```

## Namespace Overview

| Namespace | Description |
|-----------|-------------|
| `client.image.*` | Image processing — resize, convert, compress, analyze, crop, batch |
| `client.pdf.*` | PDF tools — merge, split, compress, rotate, to_text, to_images, from_images |
| `client.ai.*` | AI generation — generate image/video, transcribe, remove-bg, OCR |
| `client.web.*` | Web page tools — screenshot, html-to-pdf, article extract |
| `client.intel.*` | Intelligence — DNS, SSL, OG preview, country, timezone, regex, text stats, color |
| `client.tools.*` | Utilities — CSV, case, slugify, lorem, zip, video utils, cron validate |
| `client.agent.*` | Agent substrate — identity, approvals, receipts, jobs, heartbeat, shop, provisioning |
| `client.mailbox.*` | Mailbox — create, post, poll, peek, claim |
| `client.artifact.*` | Artifact store — upload, get, download raw |
| `client.pastebin.*` | Text pastes |
| `client.qrcode.*` | QR code generation |
| `client.shortener.*` | URL shortening |
| `client.webhook.*` | Webhook inboxes |
| `client.jwt.*` | JWT decoding |
| `client.json_tools.*` | JSON formatting, validation, minification |
| `client.dev.*` | Developer tools — IP, UUID, password, hash, base64, units, timestamps, diff |

## Detailed API Reference

### Image Tools (`client.image.*`)

| Method | Description |
|--------|-------------|
| **resize** | Resize to exact dimensions or aspect-ratio constrained |
| **convert** | Convert between JPEG, PNG, WebP, AVIF |
| **compress** | Reduce file size with quality control |
| **analyze** | Extract image metadata (dimensions, EXIF, color space) |
| **crop** | Crop by coordinates |
| **batch_process** | Process multiple images in one go |

### PDF Tools (`client.pdf.*`)

| Method | Description |
|--------|-------------|
| **merge** | Combine multiple PDFs |
| **split** | Split into individual pages |
| **compress** | Reduce file size |
| **rotate** | Rotate pages |
| **to_text** | Extract text content |
| **to_images** | Convert pages to PNG |
| **from_images** | Create PDF from images |

### AI Generation (`client.ai.*`) — requires api_key

| Method | Description |
|--------|-------------|
| **generate_image** | Generate an image from a text prompt |
| **get_generate_image_job** | Poll an image generation job |
| **generate_video** | Generate a video from a text prompt |
| **get_generate_video_job** | Poll a video generation job |
| **list_video_models** | List available video models |
| **transcribe** | Transcribe audio to text |
| **remove_bg** | Remove image background |
| **ocr** | Extract text from images/documents |
| **extract_structured** | Extract structured data from documents |

### Web Tools (`client.web.*`)

| Method | Description |
|--------|-------------|
| **screenshot** | Take a screenshot of a web page |
| **html_to_pdf** | Convert a web page to PDF |
| **article_extract** | Extract readable article content |

### Intel Tools (`client.intel.*`)

| Method | Description |
|--------|-------------|
| **dns_lookup** | DNS record lookup |
| **dns_email_security** | Check SPF, DKIM, DMARC records |
| **ssl_check** | Check SSL/TLS certificate |
| **og_preview** | Get Open Graph metadata |
| **country_lookup** | Look up country info |
| **timezone_convert** | Convert between timezones |
| **timezone_list** | List all timezones |
| **timezone_now** | Current time in a timezone |
| **regex_test** | Test a regex pattern |
| **regex_reference** | Regex syntax reference |
| **text_stats** | Text statistics |
| **color_convert** | Convert between color formats |
| **color_names** | Named CSS colors |

### Utility Tools (`client.tools.*`)

| Method | Description |
|--------|-------------|
| **csv_convert** | Convert CSV to JSON/XML |
| **case_convert** | Convert text case |
| **slugify** | Create URL-friendly slugs |
| **lorem_ipsum** | Generate placeholder text |
| **url_parse** | Parse URL components |
| **http_status** | HTTP status code info |
| **mime_lookup** | MIME type lookup |
| **html_to_md** | HTML to Markdown |
| **zip_files** | Create ZIP archives |
| **unzip** | Extract ZIP archives |
| **cron_validate** | Validate cron expressions |
| **video_info** | Video metadata |
| **video_thumbnail** | Generate video thumbnail |
| **video_gif** | Generate animated GIF from video |
| **video_extract_audio** | Extract audio from video |

### Agent Substrate (`client.agent.*`) — requires api_key

| Method | Description |
|--------|-------------|
| **claim_identity** | Claim/update agent identity handle |
| **get_identity** | Get current agent identity |
| **get_identity_by_handle** | Look up identity by handle |
| **directory** | Search public agent directory |
| **get_policy** | Get spend policy |
| **create_approval** | Create approval request |
| **list_approvals** | List pending approvals |
| **get_approval** | Get approval details |
| **list_receipts** | List signed receipts |
| **create_receipt** | Create signed receipt |
| **get_receipt** | Get receipt by ID |
| **verify_receipt** | Verify receipt signature |
| **create_job** | Create a new job |
| **list_jobs** | List jobs |
| **get_job** | Get job details |
| **claim_job** | Claim a job |
| **update_job** | Update a job |
| **complete_job** | Complete a job |
| **cancel_job** | Cancel a job |
| **heartbeat** | Send agent heartbeat |
| **shop_checkout** | Purchase shop items |
| **shop_purchases** | List past purchases |
| **shop_check_access** | Check shop access |
| **provision_human** | Provision human account |
| **get_provision** | Check provision status |
| **provision_lookup** | Look up provisioning info |
| **claim_provision** | Claim pending provision |

### Mailbox (`client.mailbox.*`)

| Method | Description |
|--------|-------------|
| **create** | Create a mailbox |
| **post** | Post a message |
| **poll** | Long-poll for new messages |
| **peek** | Peek at messages |
| **claim** | Claim mailbox for agent key |

### Artifact Store (`client.artifact.*`)

| Method | Description |
|--------|-------------|
| **upload** | Upload a file artifact |
| **get** | Get artifact metadata |
| **raw** | Download raw artifact content |

## Requirements

- Python 3.8+
- `requests` (automatically installed)

## Documentation

Full API docs: [https://agentmediatools.com/docs](https://agentmediatools.com/docs)

## License

MIT