How to Build Image Pipelines for AI Agents (2026)

Why pipelines matter for agents

For a human, calling four endpoints in a row is a minor inconvenience. For an AI agent it is the main cost. Every separate tool call is a round-trip: the agent spends tokens to describe the operation, waits for a response, then spends more tokens to describe the next step and pass the intermediate file along. Four operations means four times that overhead. A pipeline collapses the chain into one request and one response, so the agent pays the token cost once. In a real run, a 314 KB screenshot went through crop → resize → WebP → compress and came out at 8.7 KB (−97%) — in a single call.

Anatomy of a pipeline call

The pipeline tool takes a source image (as base64 or a URL) and an ordered steps array. Each step is an object with an op and its params. Chainable ops include compress, resize, crop, convert, rotate, flip, grayscale, blur, adjust, tint, negate, flatten, border, round and watermark.

{
  "imageUrl": "https://example.com/photo.jpg",
  "steps": [
    { "op": "crop",     "params": { "ratio": "16:9" } },
    { "op": "resize",   "params": { "width": 1200 } },
    { "op": "convert",  "params": { "format": "webp", "quality": 80 } },
    { "op": "compress", "params": { "quality": 75 } }
  ]
}

The server runs the steps in order and returns only the final image. You are billed 1 credit per step, and a failed step refunds the whole call.

Ready-made flows to copy

Web-optimize (or just call the optimize_for_web tool, which does this in one step):

[
  { "op": "resize",  "params": { "width": 1920, "height": 1920, "fit": "inside" } },
  { "op": "convert", "params": { "format": "webp", "quality": 80 } }
]

Thumbnail (square crop, small, compressed):

[
  { "op": "crop",     "params": { "ratio": "1:1" } },
  { "op": "resize",   "params": { "width": 400 } },
  { "op": "convert",  "params": { "format": "webp", "quality": 70 } }
]

Social square with a watermark:

[
  { "op": "crop",      "params": { "ratio": "1:1" } },
  { "op": "resize",    "params": { "width": 1080 } },
  { "op": "watermark", "params": { "text": "@yourbrand", "position": "bottom-right", "opacity": 0.6 } },
  { "op": "convert",   "params": { "format": "jpeg", "quality": 85 } }
]

Flows that mix editing and AI

The pipeline chains deterministic image ops. AI vision tools (describe, alt text, OCR, tags, filename) return text, so an agent composes them itself around a pipeline. Common agent patterns:

• Publish-ready: run optimize_for_web, then alt_text and suggest_filename on the same image — a web-ready file plus its accessibility text and SEO filename.
• Read then shrink: extract_text (OCR) to capture what a screenshot says, then a compress pipeline to store it small.
• Catalogue: describe + tags to index a photo library, with a thumbnail pipeline for previews.

Calling it over REST

Not using MCP? The same pipeline is a plain HTTP endpoint:

curl -X POST https://www.sammapix.com/api/v1/pipeline \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F "file=@photo.jpg" \
  -F 'steps=[{"op":"resize","params":{"width":1200}},{"op":"convert","params":{"format":"webp","quality":80}}]' \
  -o out.webp

Building flows visually (Node Studio)

Prefer to design a flow by hand before handing it to an agent? SammaPix has a visual node editor where you drop the first tool, connect the next, and watch the image transform step by step — the same chain your agent runs, built with your mouse. It is the fastest way to work out the right sequence and parameters, then copy them into a pipeline call. Explore the tools on the for-AI-agents page, or see how SammaPix stacks up against other services in our image API comparison for agents.