pictomancer 0.1.0

Python SDK for Pictomancer.ai — image processing for AI agents

pictomancer

Image processing for AI agents.
Resize, compress, convert, crop & pipeline — sub-50 ms, pay-per-request.

---

Thin async Python client for Pictomancer.ai — the image processing API built for autonomous agents. No API keys, no accounts. First 50 requests free, then micropayments via x402 (USDC on Base L2).

Install

pip install pictomancer

With LangChain support:

pip install pictomancer[langchain]

Quick start

import asyncio
from pictomancer import Pictomancer

async def main():
    async with Pictomancer() as p:
        # Free — get image metadata
        info = await p.analyze("https://example.com/photo.jpg")
        print(f"{info.size_bytes:,} bytes")

        # Resize to 50%
        data = await p.resize("https://example.com/photo.jpg", scale=0.5)

        # Compress to q=70 WebP
        data = await p.compress("https://example.com/photo.jpg", q=70, format="webp")

        # Convert PNG → WebP
        data = await p.convert("https://example.com/photo.png", format="webp")

        # Crop a region
        data = await p.crop("https://example.com/photo.jpg",
                            x=0, y=0, width=800, height=600)

asyncio.run(main())

Pipeline

Chain up to 10 operations in a single request:

from pictomancer import Pictomancer, PipelineOp

async with Pictomancer() as p:
    data = await p.pipeline("https://example.com/photo.jpg", [
        PipelineOp(type="resize",   params={"scale": "0.5"}),
        PipelineOp(type="compress", params={"q": "70"}),
        PipelineOp(type="convert",  params={"format": "webp"}),
    ])

Supported formats

Query at runtime with await p.info(), or see the full list:

Format	Extensions	Key options
JPEG	.jpg	q (1–100), strip, interlace
PNG	.png	compression (0–9), palette, strip
WebP	.webp	q (1–100), lossless, strip
TIFF	.tiff	compression (deflate, lzw, zstd…), q
GIF	.gif	dither (0–1), effort, bitdepth

LangChain

from pictomancer.langchain import pictomancer_tools

tools = pictomancer_tools()

# 5 tools: analyze, resize, compress, convert, crop
# Pass to any LangChain agent, LangGraph tool node, or chain

Each tool includes pricing in its description so cost-aware agents can make informed decisions.

x402 payments

The first 50 requests per agent are free. After that, agents pay automatically via x402 — USDC on Base L2.

Pass a wallet address for identity tracking:

async with Pictomancer(wallet="0xYourAgentWallet") as p:
    data = await p.resize("https://example.com/photo.jpg", scale=0.5)

Pricing

Operation	Base cost	What it does
analyze	Free	Image metadata (size in bytes)
resize	$0.001	Scale by factor
compress	$0.001	Re-encode with quality control
convert	$0.002	Format conversion
crop	$0.001	Extract rectangular region
pipeline	Per-op	Chain operations, volume discount at 3+

Size multipliers: <1 MB → 1×, 1–5 MB → 1.5×, 5–10 MB → 2×, 10–50 MB → 3×.

MCP

You can also connect directly to the hosted MCP server — no SDK needed:

{
  "mcpServers": {
    "pictomancer": {
      "url": "https://api.pictomancer.ai/mcp"
    }
  }
}

Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Links

• API Documentation
• OpenAPI Spec
• Website
• MCP Registry — ai.pictomancer/image-processing

License

MIT