DEV Community: Iteration Layer

From PDF Invoices to Formatted Spreadsheets in Two API Calls

Iteration Layer — Mon, 20 Apr 2026 23:34:22 +0000

The Invoice Spreadsheet Problem

Every accounting team has the same workflow. Invoices arrive as PDFs — from vendors, contractors, service providers. Someone needs to get that data into a spreadsheet for reconciliation, approval, or import into accounting software.

The manual version: open the PDF, copy the line items, paste into Excel, fix the formatting, repeat for the next invoice. The automated version usually involves an OCR service, a pile of regex to parse the output, and a separate process to generate the spreadsheet. Two different systems, two different failure modes, and a lot of glue code in between.

The core problem is the gap between extraction and generation. You get structured data out of a document, but then you need to transform it into a completely different format using a completely different tool. That's where the bugs live.

Extract Then Generate

The Document Extraction API and the Sheet Generation API are designed to compose. The extraction output — structured JSON with typed fields — maps directly to sheet rows. No intermediate transformation layer, no format juggling.

Here's the full pipeline: PDF in, formatted XLSX out.

Step 1: Define the Extraction Schema

First, tell the Document Extraction API what fields to look for in your invoice. The schema describes the structure you expect.

{
  "vendor_name": {
    "type": "text"
  },
  "invoice_number": {
    "type": "text"
  },
  "invoice_date": {
    "type": "date"
  },
  "due_date": {
    "type": "date"
  },
  "line_items": {
    "type": "array",
    "items": {
      "description": {
        "type": "text"
      },
      "quantity": {
        "type": "number"
      },
      "unit_price": {
        "type": "currency"
      },
      "total": {
        "type": "currency"
      }
    }
  },
  "subtotal": {
    "type": "currency"
  },
  "tax": {
    "type": "currency"
  },
  "total_due": {
    "type": "currency"
  }
}

Step 2: Extract the Invoice Data

Send the PDF to the extraction endpoint with your schema. The API returns structured JSON with typed values and confidence scores.

import { IterationLayer } from "iterationlayer";
const client = new IterationLayer({
  apiKey: "YOUR_API_KEY",
});

const extractionResult = await client.extract({
  file: invoiceBase64,
  schema: {
    vendor_name: {
      type: "text",
    },
    invoice_number: {
      type: "text",
    },
    invoice_date: {
      type: "date",
    },
    due_date: {
      type: "date",
    },
    line_items: {
      type: "array",
      items: {
        description: {
          type: "text",
        },
        quantity: {
          type: "number",
        },
        unit_price: {
          type: "currency",
        },
        total: {
          type: "currency",
        },
      },
    },
    subtotal: {
      type: "currency",
    },
    tax: {
      type: "currency",
    },
    total_due: {
      type: "currency",
    },
  },
});

const fields = extractionResult.data.fields;

{
  "success": true,
  "data": {
    "fields": {
      "vendor_name": {
        "value": "Acme Services LLC",
        "confidence": 0.97
      },
      "invoice_number": {
        "value": "INV-2026-0042",
        "confidence": 0.99
      },
      "invoice_date": {
        "value": "2026-03-15",
        "confidence": 0.95
      },
      "due_date": {
        "value": "2026-04-14",
        "confidence": 0.94
      },
      "line_items": {
        "value": [
          {
            "description": {
              "value": "Consulting services",
              "confidence": 0.96
            },
            "quantity": {
              "value": 40,
              "confidence": 0.98
            },
            "unit_price": {
              "value": 150.00,
              "confidence": 0.97
            },
            "total": {
              "value": 6000.00,
              "confidence": 0.97
            }
          }
        ],
        "confidence": 0.96
      },
      "subtotal": {
        "value": 6000.00,
        "confidence": 0.97
      },
      "tax": {
        "value": 495.00,
        "confidence": 0.95
      },
      "total_due": {
        "value": 6495.00,
        "confidence": 0.98
      }
    }
  }
}

The extraction result gives you typed fields: fields.vendor_name.value is a string, fields.line_items.value is an array, fields.total_due.value is a number. Each field also carries a confidence score so you can flag low-confidence extractions for review.

Step 3: Build the Spreadsheet

Map the extracted data directly into the sheet generation payload. The line items become rows. The invoice metadata goes into a header section.

import { IterationLayer } from "iterationlayer";
const client = new IterationLayer({
  apiKey: "YOUR_API_KEY",
});

const lineItemRows = fields.line_items.value.map((item) => [
  {
    value: item.description.value,
  },
  {
    value: item.quantity.value,
    format: "number",
  },
  {
    value: item.unit_price.value,
    format: "currency",
    currency_code: "USD",
  },
  {
    value: item.total.value,
    format: "currency",
    currency_code: "USD",
  },
]);

const summaryRows = [
  [
    {
      value: "Subtotal",
      styles: {
        is_bold: true,
      },
    },
    {
      value: null,
    },
    {
      value: null,
    },
    {
      value: fields.subtotal.value,
      format: "currency",
      currency_code: "USD",
    },
  ],
  [
    {
      value: "Tax",
      styles: {
        is_bold: true,
      },
    },
    {
      value: null,
    },
    {
      value: null,
    },
    {
      value: fields.tax.value,
      format: "currency",
      currency_code: "USD",
    },
  ],
  [
    {
      value: "Total Due",
      styles: {
        is_bold: true,
        font_size_in_pt: 12,
      },
    },
    {
      value: null,
    },
    {
      value: null,
    },
    {
      value: fields.total_due.value,
      format: "currency",
      currency_code: "USD",
      styles: {
        is_bold: true,
        font_size_in_pt: 12,
      },
    },
  ],
];

const sheetResult = await client.generateSheet({
  format: "xlsx",
  styles: {
    header: {
      is_bold: true,
      background_color: "#2d3748",
      font_color: "#ffffff",
    },
    body: {
      font_size_in_pt: 10,
    },
  },
  sheets: [
    {
      name: `Invoice ${fields.invoice_number.value}`,
      columns: [
        {
          name: "Description",
          width: 35,
        },
        {
          name: "Quantity",
          width: 12,
        },
        {
          name: "Unit Price",
          width: 16,
        },
        {
          name: "Total",
          width: 16,
        },
      ],
      rows: [...lineItemRows, ...summaryRows],
    },
  ],
});

{
  "success": true,
  "data": {
    "buffer": "UEsDBBQAAAAIAA...",
    "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
  }
}

Two API calls. The PDF becomes structured data, and the structured data becomes a formatted spreadsheet. No local PDF parser, no XLSX library, no intermediate file formats.

Scaling to Multiple Invoices

The single-invoice pipeline extends naturally to batch processing. Extract all invoices, then consolidate them into one spreadsheet with multiple sheets — or one sheet with all line items.

import { IterationLayer } from "iterationlayer";
const client = new IterationLayer({
  apiKey: "YOUR_API_KEY",
});

const invoiceFiles = ["invoice-001.pdf", "invoice-002.pdf", "invoice-003.pdf"];

const sheets = await Promise.all(
  invoiceFiles.map(async (filename) => {
    const pdf = await Bun.file(filename).arrayBuffer();
    const pdfBase64 = Buffer.from(pdf).toString("base64");

    const extraction = await client.extract({
      file: pdfBase64,
      schema: extractionSchema,
    });

    const invoiceFields = extraction.data.fields;

    return {
      name: `Invoice ${invoiceFields.invoice_number.value}`,
      columns: [
        {
          name: "Description",
          width: 35,
        },
        {
          name: "Quantity",
          width: 12,
        },
        {
          name: "Unit Price",
          width: 16,
        },
        {
          name: "Total",
          width: 16,
        },
      ],
      rows: invoiceFields.line_items.value.map((item) => [
        {
          value: item.description.value,
        },
        {
          value: item.quantity.value,
          format: "number",
        },
        {
          value: item.unit_price.value,
          format: "currency",
          currency_code: "USD",
        },
        {
          value: item.total.value,
          format: "currency",
          currency_code: "USD",
        },
      ]),
    };
  }),
);

const consolidatedResult = await client.generateSheet({
  format: "xlsx",
  styles: {
    header: {
      is_bold: true,
      background_color: "#2d3748",
      font_color: "#ffffff",
    },
  },
  sheets,
});

{
  "success": true,
  "data": {
    "buffer": "UEsDBBQAAAAIAA...",
    "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
  }
}

Each invoice gets its own sheet tab. One XLSX file, all invoices, properly formatted.

When to Use This Pipeline

This extract-then-generate pattern works for any document-to-spreadsheet workflow:

Invoices — Vendor invoices to accounts payable spreadsheets
Receipts — Expense receipts to expense reports
Purchase orders — PO documents to procurement tracking sheets
Contracts — Contract terms to comparison matrices
Bank statements — PDF statements to transaction logs

The key insight is that document structure maps cleanly to spreadsheet structure. A table in a PDF maps to rows and columns. Currency values map to formatted currency cells. Dates map to date-formatted cells. The extraction gives you typed data, and the sheet generation consumes typed data. No parsing, no regex, no format conversion in between.

Get Started

The Document Extraction docs cover schema design and field types. The Sheet Generation docs cover the full spreadsheet API including styles, formulas, and multi-sheet support.

Both APIs use the same authentication and the same response format. If you're already using one, adding the other takes minutes. Sign up for a free account to try the pipeline yourself.

Image Processing for E-Commerce: Resize, Watermark, and Optimize in One API Call

Iteration Layer — Mon, 20 Apr 2026 23:34:17 +0000

Every Marketplace Wants Something Different

If you sell products on more than one platform, you already know the pain. Amazon wants 1,000 x 1,000 pixels minimum on a pure white background. Shopify themes look best at 2,048 x 2,048. Etsy recommends 2,000 pixels on the shortest side. eBay wants at least 500 x 500 but renders thumbnails at 300 x 300. Your own website needs WebP for performance, JPEG for email campaigns, and a compressed version under 200 KB for mobile push notifications.

That is five different size requirements, three different formats, and a background removal step — for a single product photo. Multiply by a catalog of 500 SKUs and you have a pipeline problem, not an image problem.

Most teams cobble this together. A Sharp script in a Docker container. A cron job that watches an S3 bucket. A Lambda function that calls ImageMagick. Maybe Cloudinary for the CDN part, but now you are managing two systems. Every new marketplace means another resize preset, another format branch, another edge case where a CMYK TIFF or a transparent PNG breaks the pipeline at 3 AM.

The individual operations are not hard. Resizing an image is a solved problem. What is hard is chaining those operations together across formats, sizes, and quality targets — without maintaining the infrastructure yourself.

One Request, Multiple Operations

The Image Transformation API takes a different approach. Instead of running a series of tools in sequence, you describe the entire transformation chain in a single request. The API executes the operations in order, passes the result of each step to the next, and returns the final image.

Here is the simplest case: resize a product photo and convert it to WebP.

import { IterationLayer } from "iterationlayer";

const client = new IterationLayer({
  apiKey: "YOUR_API_KEY",
});

const result = await client.transform({
  file: {
    type: "url",
    name: "product.jpg",
    url: "https://example.com/images/product.jpg",
  },
  operations: [
    {
      type: "resize",
      width_in_px: 1000,
      height_in_px: 1000,
      fit: "contain",
    },
    {
      type: "convert",
      format: "webp",
      quality: 85,
    },
  ],
});

{
  "success": true,
  "data": {
    "buffer": "<base64-encoded image>",
    "mime_type": "image/webp"
  }
}

Two operations, one request. The contain fit mode keeps the aspect ratio intact and fits the image within the target dimensions. The response is a base64-encoded buffer you can write directly to disk or upload to your CDN.

That is the foundation. The real value comes when you start chaining more operations together.

Background Removal for White-Background Requirements

Amazon, Google Shopping, and most comparison shopping engines require a white or neutral background. If your product photos come from a studio with a gray backdrop, or from a supplier who shoots on a wooden table, you need to remove the background before uploading.

The remove_background operation detects the foreground subject and strips away everything else. You can optionally replace the removed background with a solid color — white for Amazon, transparent for your own website where you composite on custom backgrounds.

const result = await client.transform({
  file: {
    type: "url",
    name: "product-raw.jpg",
    url: "https://example.com/images/product-raw.jpg",
  },
  operations: [
    {
      type: "remove_background",
      background_hex_color: "#FFFFFF",
    },
    {
      type: "resize",
      width_in_px: 1000,
      height_in_px: 1000,
      fit: "contain",
    },
    {
      type: "convert",
      format: "jpeg",
      quality: 90,
    },
  ],
});

Three operations in sequence: remove the background and replace with white, resize to 1,000 x 1,000, convert to JPEG. The output is ready for Amazon without any intermediate files.

If you skip the background_hex_color parameter, the background is removed entirely — you get a transparent PNG. Useful when you want to composite the product onto seasonal promotional backgrounds or custom brand templates.

Smart Crop for Thumbnails and Listing Images

Standard cropping cuts from a fixed point — top-left, center, whatever you specify. That works until your product is off-center in the original photo, and a center crop chops off half the item.

The smart_crop operation analyzes the image to detect the primary subject, then crops around it. The product stays centered in the output regardless of where it sits in the original frame.

This is critical for thumbnail grids. When a shopper scrolls through a search results page, every listing image needs to show the product clearly at small sizes. A generic center crop risks cutting off a shoe's toe, a lamp's shade, or a bag's handle.

const result = await client.transform({
  file: {
    type: "url",
    name: "product.jpg",
    url: "https://example.com/images/product.jpg",
  },
  operations: [
    {
      type: "remove_background",
      background_hex_color: "#FFFFFF",
    },
    {
      type: "smart_crop",
      width_in_px: 300,
      height_in_px: 300,
    },
    {
      type: "convert",
      format: "webp",
      quality: 80,
    },
  ],
});

Background removal first, then smart crop, then format conversion. The output is a 300 x 300 WebP thumbnail with the product centered and the background clean.

Compress to a Target File Size

Email service providers and push notification platforms enforce strict file size limits. Mailchimp caps inline images at 1 MB. Push notifications on iOS work best under 100 KB. Some ad networks reject creatives over 150 KB.

The compress_to_size operation takes a target in bytes and automatically adjusts quality and dimensions to hit that target. You do not need to guess the quality setting or run a trial-and-error loop.

const result = await client.transform({
  file: {
    type: "url",
    name: "hero-image.jpg",
    url: "https://example.com/images/hero-image.jpg",
  },
  operations: [
    {
      type: "resize",
      width_in_px: 600,
      height_in_px: 400,
      fit: "cover",
    },
    {
      type: "compress_to_size",
      max_file_size_in_bytes: 102_400,
    },
  ],
});

The API figures out the optimal quality and compression settings to land at or below 100 KB. No more iterating through quality levels in a loop until the output is small enough.

Upscaling Low-Resolution Supplier Images

Supplier catalogs are notorious for low-resolution images. You get a 400 x 400 pixel photo from a wholesale catalog, and your storefront needs 2,000 x 2,000 for the zoom viewer. Naive upscaling produces blurry results. The upscale operation uses AI-based super-resolution to increase image dimensions by 2x, 3x, or 4x while preserving detail.

Chain it with the rest of your pipeline:

const result = await client.transform({
  file: {
    type: "url",
    name: "supplier-photo.jpg",
    url: "https://example.com/supplier/photo.jpg",
  },
  operations: [
    {
      type: "upscale",
      factor: 4,
    },
    {
      type: "remove_background",
      background_hex_color: "#FFFFFF",
    },
    {
      type: "resize",
      width_in_px: 2000,
      height_in_px: 2000,
      fit: "contain",
    },
    {
      type: "sharpen",
      sigma: 1.5,
    },
    {
      type: "convert",
      format: "webp",
      quality: 90,
    },
  ],
});

Five operations in one request: upscale the 400 x 400 image to 1,600 x 1,600, remove the background, resize to the target 2,000 x 2,000, sharpen to recover crispness, and convert to WebP. A supplier thumbnail becomes a marketplace-ready hero image.

The Full E-Commerce Pipeline

The real workflow is not a single transformation — it is generating multiple variants from one source image. Your product listing needs a main image, a thumbnail, an email-safe version, and a social media card. Each has different dimensions, formats, and quality targets.

With a composable API, you make one request per variant. Here is a complete pipeline for preparing a product image for multi-channel distribution. Each call starts from the same source image.

Main listing image — 2,000 x 2,000, white background, WebP:

// Main listing image
const mainImage = await client.transform({
  file: {
    type: "url",
    name: "product.jpg",
    url: "https://example.com/images/product.jpg",
  },
  operations: [
    {
      type: "remove_background",
      background_hex_color: "#FFFFFF",
    },
    {
      type: "resize",
      width_in_px: 2000,
      height_in_px: 2000,
      fit: "contain",
    },
    {
      type: "convert",
      format: "webp",
      quality: 90,
    },
  ],
});

Thumbnail — 300 x 300, smart-cropped, WebP:

// Thumbnail
const thumbnail = await client.transform({
  file: {
    type: "url",
    name: "product.jpg",
    url: "https://example.com/images/product.jpg",
  },
  operations: [
    {
      type: "remove_background",
      background_hex_color: "#FFFFFF",
    },
    {
      type: "smart_crop",
      width_in_px: 300,
      height_in_px: 300,
    },
    {
      type: "convert",
      format: "webp",
      quality: 80,
    },
  ],
});

Email-safe version — 600 x 400, JPEG, under 100 KB:

// Email-safe version
const emailImage = await client.transform({
  file: {
    type: "url",
    name: "product.jpg",
    url: "https://example.com/images/product.jpg",
  },
  operations: [
    {
      type: "remove_background",
      background_hex_color: "#FFFFFF",
    },
    {
      type: "resize",
      width_in_px: 600,
      height_in_px: 400,
      fit: "cover",
    },
    {
      type: "convert",
      format: "jpeg",
    },
    {
      type: "compress_to_size",
      max_file_size_in_bytes: 102_400,
    },
  ],
});

Three API calls, three variants, zero infrastructure. The same product image goes to your storefront, your search results grid, and your email campaign — each in the right format and size.

Format Conversion: WebP, AVIF, JPEG, and When to Use What

Not every format works everywhere. WebP has near-universal browser support and delivers excellent quality-to-size ratios. AVIF is smaller still but has spotty support in older browsers and email clients. JPEG remains the safest choice for email and legacy platforms. PNG is necessary when you need transparency.

The convert operation handles the translation. Pair it with quality settings to control the tradeoff between file size and visual fidelity.

A practical strategy for e-commerce:

Storefront hero images: WebP at quality 90. Best balance of quality and file size for modern browsers.
Category page thumbnails: WebP at quality 75-80. Smaller file sizes improve page load speed on grid layouts.
Email campaigns: JPEG at quality 85. Universal compatibility across email clients.
Product zoom viewer: AVIF at quality 90 with a JPEG fallback. AVIF gives the smallest file size at high quality, critical for large zoomable images.
Images with transparency: PNG. The only format in this list that supports full alpha channels across all clients.

Each of these is a single convert operation at the end of your transformation chain. The format conversion applies after all other operations — resize first, crop second, convert last.

Chaining with Other APIs

Image transformation is one step in a larger workflow. Consider the full product onboarding pipeline for a marketplace seller.

A supplier sends a PDF catalog with product descriptions and embedded images. You need to extract the product data, process the images, and generate listing-ready assets. With composable APIs, that becomes three chained steps:

Extract the product data from the PDF catalog using the Document Extraction API — names, descriptions, prices, and SKU numbers come back as structured JSON with confidence scores.
Transform each product image using the Image Transformation API — remove backgrounds, resize for marketplace requirements, convert to WebP.
Generate social media cards or promotional banners using the Image Generation API — composite the product onto branded templates with pricing overlays.

Each step uses the same API key, the same credit pool, and the same error format. No glue code between vendors. No format conversion between services. The structured JSON from step one contains the product names and prices that go into the templates in step three.

Where the DIY Approach Still Wins

If you process fewer than a dozen images a month and your requirements never change, a Sharp script or an ImageMagick command works fine. The cost is zero and the control is total.

The calculus shifts when your catalog grows, your marketplace requirements multiply, or your operations team spends hours manually processing images. At that point, maintaining the Docker container, debugging the CMYK edge case, and adding the new AVIF conversion path costs more in engineering time than the API calls.

The API also runs on EU infrastructure with zero data retention — files are processed in memory and discarded immediately. If your product images include customer-facing content or if your business operates under EU data regulations, that matters.

Available Operations

The transformation API supports chaining up to 30 operations per request. Beyond what we have covered here, you can:

Sharpen or blur with configurable sigma values
Rotate by any angle, with optional background fill color
Flip (vertical) or flop (horizontal) for mirror variations
Extend canvas with padding in any direction and color
Trim whitespace or near-uniform borders automatically
Modulate brightness, saturation, and hue
Grayscale conversion for stylized product shots
Auto-contrast for normalizing inconsistent lighting across supplier photos
Denoise for cleaning up low-quality source images

Every operation composes with every other operation. The order matters — resize before sharpen produces a different result than sharpen before resize — and you control the sequence.

Get Started

The full operation reference and SDK guides are in the Image Transformation docs. Install the TypeScript SDK (iterationlayer on npm), the Python SDK (iterationlayer on PyPI), or the Go SDK and start transforming images.

Sign up for a free account — no credit card required. Send a product image, chain a few operations, and check the result. The same request you test with one image works identically when you process your full catalog.

If your product images also need structured data — dimensions, weight, material extracted from a supplier spec sheet — the Document Extraction API chains naturally with image transformation. Same auth, same credits, same API conventions. Extract the data, transform the images, generate the listings.

Building AI Agents That Process Documents: MCP, Structured I/O, and Confidence Routing

Iteration Layer — Mon, 20 Apr 2026 23:34:13 +0000

The Agent Promise vs. the Agent Reality

Every AI agent demo looks the same. The agent gets a prompt, calls a tool, returns a result. The audience applauds. Then someone tries to build a real workflow — one that handles messy PDFs, evaluates whether the extraction is trustworthy, generates a report when it is, and flags a human when it isn't — and the demo falls apart.

The hard part of agent-based document processing is not calling an API. It is the logic between the calls. Deciding what to do with an extraction that came back at 0.72 confidence. Knowing when to generate a summary report and when to route to a review queue. Chaining extraction, evaluation, and generation into a pipeline that runs without babysitting.

This tutorial builds that pipeline end-to-end. You will build an agent workflow that extracts structured data from documents, evaluates confidence scores to decide the next step, and either generates a PDF report or flags the document for human review. The code is real, the confidence routing is real, and the pipeline works with any MCP-compatible client.

What You Are Building

The complete workflow has three stages:

Extract — Parse a document (invoice, contract, report) into structured JSON with per-field confidence scores
Evaluate — Check confidence scores against thresholds to decide whether the extraction is trustworthy
Route — If confidence is high, generate a PDF summary report. If confidence is low, flag the document for manual review.

This is not a single API call. It is a multi-step pipeline where the output of one stage determines the behavior of the next. That is where agents earn their keep — not in making one call, but in making the right sequence of calls based on what the data tells them.

Prerequisites

You need an Iteration Layer account (free tier works) and an MCP-compatible client. The examples below show both the MCP-based approach (for agents like Claude Code and Cursor) and the direct SDK approach (for building this into your own application code).

MCP Setup for Claude Code:

claude mcp add iterationlayer --transport http https://api.iterationlayer.com/mcp

MCP Setup for Cursor (add to .cursor/mcp.json):

{
  "mcpServers": {
    "iterationlayer": {
      "type": "http",
      "url": "https://api.iterationlayer.com/mcp"
    }
  }
}

Authentication uses OAuth 2.1 — a browser window opens on first use to authorize access. No API keys in config files.

For the SDK approach, install the SDK for your language:

npm install iterationlayer

Stage 1: Extracting Structured Data from a Document

The first step is turning an unstructured document into structured JSON. The key difference between a basic extraction and an agent-ready extraction is the confidence scores. Every field in the response includes a confidence value between 0 and 1. This is what makes routing possible — without it, the agent has no signal for deciding what to trust.

Here is an extraction that pulls key fields from a supplier invoice — vendor name, invoice number, total amount, currency, due date, and line items:

import { IterationLayer } from "iterationlayer";

const client = new IterationLayer({
  apiKey: "YOUR_API_KEY",
});

const extraction = await client.extract({
  files: [
    {
      type: "url",
      name: "supplier-invoice-2026-0892.pdf",
      url: "https://example.com/invoices/supplier-invoice-2026-0892.pdf",
    },
  ],
  schema: {
    fields: [
      {
        name: "vendor_name",
        type: "TEXT",
        description: "Name of the company that issued the invoice",
      },
      {
        name: "invoice_number",
        type: "TEXT",
        description: "Invoice number or reference code",
      },
      {
        name: "total_amount",
        type: "CURRENCY_AMOUNT",
        description: "Total amount due on the invoice",
        decimal_points: 2,
      },
      {
        name: "currency",
        type: "CURRENCY_CODE",
        description: "Currency of the invoice",
      },
      {
        name: "due_date",
        type: "DATE",
        description: "Payment due date",
      },
      {
        name: "line_items",
        type: "ARRAY",
        description: "Individual line items on the invoice",
        fields: [
            {
              name: "description",
              type: "TEXT",
              description: "Line item description",
            },
            {
              name: "quantity",
              type: "INTEGER",
              description: "Number of units",
            },
            {
              name: "unit_price",
              type: "CURRENCY_AMOUNT",
              description: "Price per unit",
              decimal_points: 2,
            },
          ],
      },
    ],
  },
});

The response includes per-field confidence scores and citations:

{
  "vendor_name": {
    "value": "Bergmann Elektronik GmbH",
    "confidence": 0.97,
    "citations": ["Bergmann Elektronik GmbH"],
    "source": "supplier-invoice-2026-0892.pdf",
    "type": "TEXT"
  },
  "invoice_number": {
    "value": "BE-2026-0892",
    "confidence": 0.99,
    "citations": ["Rechnung Nr. BE-2026-0892"],
    "source": "supplier-invoice-2026-0892.pdf",
    "type": "TEXT"
  },
  "total_amount": {
    "value": 12450.00,
    "confidence": 0.95,
    "citations": ["Gesamtbetrag: 12.450,00"],
    "source": "supplier-invoice-2026-0892.pdf",
    "type": "CURRENCY_AMOUNT"
  },
  "currency": {
    "value": "EUR",
    "confidence": 0.98,
    "citations": ["EUR"],
    "source": "supplier-invoice-2026-0892.pdf",
    "type": "CURRENCY_CODE"
  },
  "due_date": {
    "value": "2026-05-15",
    "confidence": 0.93,
    "citations": ["Zahlungsziel: 15.05.2026"],
    "source": "supplier-invoice-2026-0892.pdf",
    "type": "DATE"
  },
  "line_items": {
    "value": [
      {
        "description": {
          "value": "Leiterplatten Typ A (200 Stk.)",
          "confidence": 0.94,
          "citations": ["Leiterplatten Typ A (200 Stk.)"],
          "source": "supplier-invoice-2026-0892.pdf",
          "type": "TEXT"
        },
        "quantity": {
          "value": 200,
          "confidence": 0.96,
          "citations": ["200"],
          "source": "supplier-invoice-2026-0892.pdf",
          "type": "INTEGER"
        },
        "unit_price": {
          "value": 42.50,
          "confidence": 0.93,
          "citations": ["42,50"],
          "source": "supplier-invoice-2026-0892.pdf",
          "type": "CURRENCY_AMOUNT"
        }
      },
      {
        "description": {
          "value": "Steckverbinder Set B (500 Stk.)",
          "confidence": 0.95,
          "citations": ["Steckverbinder Set B (500 Stk.)"],
          "source": "supplier-invoice-2026-0892.pdf",
          "type": "TEXT"
        },
        "quantity": {
          "value": 500,
          "confidence": 0.97,
          "citations": ["500"],
          "source": "supplier-invoice-2026-0892.pdf",
          "type": "INTEGER"
        },
        "unit_price": {
          "value": 7.90,
          "confidence": 0.91,
          "citations": ["7,90"],
          "source": "supplier-invoice-2026-0892.pdf",
          "type": "CURRENCY_AMOUNT"
        }
      }
    ],
    "confidence": 0.93,
    "citations": [],
    "source": "supplier-invoice-2026-0892.pdf",
    "type": "ARRAY"
  }
}

Every field has a confidence score. Every field has citations showing the exact text from the source document that supports the extracted value. This is the foundation the agent needs to make routing decisions.

Stage 2: Confidence-Based Routing

Here is where the agent logic lives. You have structured data with confidence scores. Now you need rules.

A simple but effective routing strategy uses two thresholds:

High confidence (all fields >= 0.90): Auto-generate the report. No human review needed.
Low confidence (any field < 0.90): Flag the document. Route to a review queue with the specific fields that need attention.

This is not a magic number — 0.90 is a reasonable starting point for most document types. Adjust based on your tolerance for errors. Financial documents might use 0.95. Internal summaries might use 0.85.

const CONFIDENCE_THRESHOLD = 0.90;

const lowConfidenceFields = Object.entries(extraction)
  .filter(([, field]) => field.confidence < CONFIDENCE_THRESHOLD)
  .map(([name, field]) => ({
    name,
    confidence: field.confidence,
    value: field.value,
  }));

const isHighConfidence = lowConfidenceFields.length === 0;

if (isHighConfidence) {
  console.log("All fields above threshold. Generating report...");
} else {
  console.log("Low confidence fields:", lowConfidenceFields);
  console.log("Routing to human review.");
}

This evaluation step is pure application logic — no API call needed. The agent reads the confidence scores from the extraction response and makes a decision. In an MCP-based agent, this decision happens naturally in conversation: the agent sees the confidence scores and decides what to do next based on the instructions you give it.

Stage 3a: Generating a Report (High Confidence Path)

When all confidence scores pass the threshold, the agent generates a PDF summary report from the extracted data. This is where composability matters — the extraction output feeds directly into document generation. Same auth, same credit pool, no format conversion.

const report = await client.generateDocument({
  format: "pdf",
  document: {
    metadata: {
      title: `Invoice Summary: ${extraction.invoice_number.value}`,
      author: "Automated Processing Pipeline",
    },
    page: {
      size: { preset: "A4" },
      margins: {
        top_in_pt: 60,
        right_in_pt: 50,
        bottom_in_pt: 60,
        left_in_pt: 50,
      },
    },
    content: [
      {
        type: "headline",
        level: "h1",
        text: "Invoice Summary",
      },
      {
        type: "paragraph",
        markdown: `**Vendor:** ${extraction.vendor_name.value}`,
      },
      {
        type: "paragraph",
        markdown: `**Invoice:** ${extraction.invoice_number.value} | **Due:** ${extraction.due_date.value} | **Total:** ${extraction.total_amount.value} ${extraction.currency.value}`,
      },
      {
        type: "headline",
        level: "h2",
        text: "Line Items",
      },
      {
        type: "table",
        header: {
          cells: [
            { text: "Description" },
            { text: "Qty" },
            { text: "Unit Price" },
            { text: "Subtotal" },
          ],
        },
        rows: (extraction.line_items.value as Array<Record<string, ExtractionFieldResult>>).map(
          (item) => ({
            cells: [
              { text: String(item.description.value) },
              { text: String(item.quantity.value), horizontal_alignment: "right" as const },
              {
                text: `${item.unit_price.value} ${extraction.currency.value}`,
                horizontal_alignment: "right" as const,
              },
              {
                text: `${(Number(item.quantity.value) * Number(item.unit_price.value)).toFixed(2)} ${extraction.currency.value}`,
                horizontal_alignment: "right" as const,
              },
            ],
          }),
        ),
      },
      { type: "separator" },
      {
        type: "paragraph",
        markdown:
          "**Processing Status:** Automatically approved. All extraction confidence scores above 0.90 threshold.",
      },
    ],
  },
});

// report.buffer contains the base64-encoded PDF
// report.mime_type is "application/pdf"

Two API calls. One credit pool. The extraction result feeds directly into document generation — no intermediate file, no format conversion, no second vendor.

Stage 3b: Flagging for Review (Low Confidence Path)

When any field falls below the confidence threshold, the agent generates a different document — a review report that highlights exactly which fields need human attention, what the extracted values were, and what the confidence scores looked like.

const reviewReport = await client.generateDocument({
  format: "pdf",
  document: {
    metadata: {
      title: `Review Required: ${extraction.invoice_number.value}`,
      author: "Automated Processing Pipeline",
    },
    page: {
      size: { preset: "A4" },
      margins: {
        top_in_pt: 60,
        right_in_pt: 50,
        bottom_in_pt: 60,
        left_in_pt: 50,
      },
    },
    content: [
      {
        type: "headline",
        level: "h1",
        text: "Review Required",
      },
      {
        type: "paragraph",
        markdown: `The following fields were extracted with confidence below the ${CONFIDENCE_THRESHOLD} threshold and require manual verification.`,
      },
      {
        type: "table",
        header: {
          cells: [
            { text: "Field" },
            { text: "Extracted Value" },
            { text: "Confidence" },
          ],
        },
        rows: lowConfidenceFields.map((field) => ({
          cells: [
            { text: field.name },
            { text: String(field.value) },
            { text: field.confidence.toFixed(2) },
          ],
        })),
      },
      { type: "separator" },
      {
        type: "headline",
        level: "h2",
        text: "All Extracted Fields",
      },
      {
        type: "table",
        header: {
          cells: [
            { text: "Field" },
            { text: "Value" },
            { text: "Confidence" },
            { text: "Status" },
          ],
        },
        rows: Object.entries(extraction).map(([name, field]) => ({
          cells: [
            { text: name },
            { text: String(field.value) },
            { text: field.confidence.toFixed(2) },
            { text: field.confidence >= CONFIDENCE_THRESHOLD ? "OK" : "REVIEW" },
          ],
        })),
      },
      {
        type: "paragraph",
        markdown: "**Source Document:** supplier-invoice-2026-0892.pdf",
      },
    ],
  },
});

The review report gives a human everything they need: which fields are below threshold, what the extracted values were, and the confidence scores for every field. No one has to re-read the original document to figure out what went wrong.

Putting It All Together: The MCP Agent Workflow

When you use this pipeline through an MCP agent (Claude Code, Cursor, Windsurf), the three stages happen in a single conversation. You describe the workflow once, and the agent orchestrates it.

Here is a prompt that captures the full pipeline:

I have a supplier invoice at https://example.com/invoices/supplier-invoice-2026-0892.pdf. Extract the vendor name, invoice number, total amount, currency, due date, and line items with descriptions, quantities, and unit prices. Then check the confidence scores: if all fields are at 0.90 or above, generate a PDF summary report with the invoice details and a line item table. If any field is below 0.90, generate a review report that lists which fields need manual verification, with their extracted values and confidence scores.

The agent calls extract_document, reads the confidence scores in the response, and decides whether to call generate_document with the summary template or the review template. No code, no scripting — just natural language describing a multi-step workflow with conditional routing.

This works because the MCP server exposes both tools (extract_document and generate_document) with full schema descriptions. The agent knows what parameters each tool expects and what the response looks like. The confidence scores in the extraction response give the agent a concrete signal for the routing decision.

Extending the Pipeline

The three-stage pattern — extract, evaluate, route — is a foundation. Here are four extensions that build on it.

Adding Image Processing to the Pipeline

If the source document includes a company logo or product images, you can add an image transformation step. After extraction, the agent calls transform_image to resize, crop, or convert images before they are embedded in the generated report.

The agent prompt extends naturally:

...and if the invoice has a supplier logo, resize it to 200x80 pixels and include it in the header of the summary report.

One more MCP tool call in the chain. Same credit pool, same auth.

Batch Processing with Confidence Aggregation

Process multiple documents and aggregate the results. Extract data from a stack of invoices, evaluate confidence across the batch, and generate a single summary spreadsheet with a column marking which rows need review.

The per-field confidence scores make this possible at scale. Instead of reviewing every document, a human reviews only the rows where confidence dropped below threshold. For a batch of 50 invoices where 45 extract cleanly, that is 45 documents that never touch a human queue.

Webhook-Based Async Processing

For large documents or high-volume pipelines, use the async variants of each API. Pass a webhook_url and the API sends the result to your endpoint when processing completes:

const asyncResult = await client.extractAsync({
  files: [
    {
      type: "url",
      name: "large-contract.pdf",
      url: "https://example.com/contracts/large-contract.pdf",
    },
  ],
  schema: {
    fields: [
      {
        name: "parties",
        type: "ARRAY",
        description: "Contract parties",
        fields: [
            {
              name: "name",
              type: "TEXT",
              description: "Party name",
            },
          ],
      },
    ],
  },
  webhook_url: "https://your-app.example.com/webhooks/extraction-complete",
});

// asyncResult.message confirms the job was queued

Your webhook endpoint receives the extraction result, runs the confidence evaluation, and triggers the appropriate document generation call. The entire pipeline runs asynchronously without blocking your application.

Per-Field Threshold Tuning

Not all fields deserve the same confidence threshold. A vendor name at 0.88 confidence is probably fine — there are only so many ways to spell a company name. A total amount at 0.88 confidence on a six-figure invoice deserves a closer look.

{
  "vendor_name": 0.85,
  "invoice_number": 0.90,
  "total_amount": 0.95,
  "currency": 0.90,
  "due_date": 0.90,
  "line_items": 0.90
}

Map field names to thresholds. Compare each field's confidence against its specific threshold instead of using a single global number. Financial fields get tighter thresholds. Descriptive fields get looser ones.

Why This Pattern Works

The extract-evaluate-route pattern works for document processing the same way CI/CD pipelines work for code: automated when the checks pass, human review when they don't.

The pieces that make this viable:

Per-field confidence scores give the agent a concrete signal for routing. Without them, every document would need human review or blind trust.
Structured I/O means the extraction output is already in the format document generation expects. No parsing, no transformation, no glue code between stages.
Composable APIs mean extraction and generation share the same auth and credit pool. Adding a third step (image transformation, spreadsheet generation) does not mean adding a third vendor.
MCP means the agent discovers and chains these tools without custom integration code. The same pipeline works in Claude Code, Cursor, Windsurf, or any MCP-compatible client.

The result is a document processing pipeline that handles the happy path automatically and only involves humans for the edge cases that actually need them.

Get Started

The full pipeline uses two APIs: Document Extraction for structured parsing with confidence scores, and Document Generation for producing PDF reports. Both are available through the MCP server or directly via the TypeScript, Python, and Go SDKs.

Sign up for a free account — no credit card required — and try the extraction with a document you already have. Check the confidence scores. If they are consistently above your threshold for your document type, you have a pipeline that runs itself.

One Credit Pool, Every Format: Why Unified Billing Matters for Content Pipelines

Iteration Layer — Mon, 20 Apr 2026 23:34:08 +0000

The Spreadsheet No One Wants to Maintain

You have a content pipeline. It extracts data from supplier invoices, transforms product images for your marketplace, and generates monthly summary reports as PDFs. Three operations, three vendors, three billing dashboards.

At the end of the month, someone — probably you — opens three separate invoices and tries to reconcile them against what actually happened. The OCR vendor charges per page. The image processing service charges per transformation. The PDF generator charges per document. Each has its own usage tiers, overage rates, and billing cycles.

This is not a hypothetical scenario. It is the default state of content processing infrastructure in 2026. And the billing complexity is the least of the problems.

The Real Cost of Per-Service Billing

Per-service billing looks simple on each vendor's pricing page. It stops looking simple the moment your workflow spans more than one service.

Budget Allocation Is Guessing

At the start of a quarter, you estimate how many pages you will extract, how many images you will transform, and how many documents you will generate. You buy capacity accordingly — or commit to tiers that give you the best per-unit rate.

Then reality happens. A client sends scanned PDFs instead of digital ones, tripling your OCR page count. Another client drops their image processing requirements entirely but needs twice as many reports. Your extraction budget is blown. Your image budget is wasted. Your document generation budget is half-used.

None of this reflects a failure on your part. It reflects the fundamental unpredictability of content workflows. The work shifts between formats and operations month to month, and per-service billing punishes you for that.

Committed Capacity Goes Stale

Most SaaS pricing models reward commitment. Buy 10,000 OCR pages/month and you get a better per-page rate than paying on demand. The problem is that committed capacity is scoped to a single operation.

Those 10,000 pages you pre-purchased do not help when your actual need is 4,000 pages of extraction and 6,000 document generations. You have unused extraction credits and an overage bill for document generation — paying more in total than if you had committed to nothing.

This is not a pricing mistake. It is a structural feature of per-service billing. The vendor sells one capability and optimizes their pricing for that capability. Your workflow spans multiple capabilities, and the pricing model actively works against that.

Dashboard Fragmentation Hides the Real Numbers

Each vendor gives you a dashboard showing your usage of their service. None of them show you the cost of your workflow.

The question you actually need to answer — "what does it cost to process one supplier catalog end-to-end?" — requires pulling data from three dashboards, normalizing the units (pages vs. transformations vs. documents), and doing the math yourself. Every time.

This is the spreadsheet no one wants to maintain. It exists in every organization that processes content across multiple vendors. It is always out of date. And it becomes critical exactly when you need to justify a budget increase or cut costs.

Alert Fatigue Across Multiple Systems

Each vendor sends usage alerts independently. You get an email at 80% of your OCR tier. A Slack notification when image processing spikes. A dashboard warning about document generation approaching its limit.

These alerts are technically useful and practically useless. They tell you about capacity within a single service, but your actual concern is total pipeline cost. A spike in one service might be perfectly fine if another service is sitting idle — but the alerts do not know that. They fire independently, creating noise without insight.

The Integration Tax

Beyond billing, per-service billing creates an integration tax that compounds over time. Each vendor has its own:

Authentication model. API keys, OAuth tokens, IAM roles — each with its own rotation policy and permission model.
Error format. One vendor returns HTTP 422 with a JSON error body. Another returns HTTP 400 with a plain text message. A third returns HTTP 200 with an error field nested inside the response.
Rate limiting. Different quotas, different backoff strategies, different headers for communicating remaining capacity.
Webhook schemas. If you use async processing, each vendor sends webhook payloads in their own format with their own retry policies.

This is not a billing problem — it is an operational problem that per-service billing makes worse. Every vendor relationship carries a maintenance cost. Three vendors means three sets of API documentation to track for breaking changes, three support channels to escalate through, and three sets of SDK dependencies to keep updated.

When all operations come from one platform, you learn one error format, one auth model, one rate limiting strategy. The integration tax is paid once, not multiplied by the number of operations in your pipeline.

Vendor Lock-in Multiplied

Switching a single vendor is straightforward. Switching three vendors simultaneously — because your pipeline depends on all three — is a project. The switching cost is not three times one vendor switch. It is worse, because the glue code between vendors is itself a dependency.

If you decide to move away from your OCR vendor, you also need to update the glue code that transforms OCR output into the format your PDF generator expects. The format assumptions are baked into every integration point. Changing one vendor often means changing two integration layers.

A unified platform reduces vendor lock-in to a single relationship. You are still locked in — that is the nature of using any external service. But one lock-in is categorically easier to manage, negotiate, and if necessary, migrate away from than three.

What Changes with Unified Credits

The alternative is a single credit pool that applies across all operations. One balance, one dashboard, one set of alerts. Credits are fungible — spend them on extraction, image transformation, image generation, document generation, spreadsheet generation, or any combination.

This is not a minor billing convenience. It changes how you plan, spend, and track content processing work.

Your Budget Flexes with Your Workflow

With a unified pool, the shift from "mostly extraction this month" to "mostly document generation next month" has zero billing impact. You bought processing capacity, not extraction capacity or generation capacity. The credits move where the work moves.

A concrete example: an e-commerce team processes product catalogs. In January, a batch of new suppliers means heavy extraction — parsing hundreds of supplier PDFs into structured product data. In February, the catalog is stable, but a marketplace expansion requires regenerating all product listing images in new dimensions and formats. In March, the quarterly report cycle means heavy document generation.

With per-service billing, each month looks like a different budget problem. With unified credits, each month uses the same pool differently. The total spend is predictable even when the per-operation mix is not.

One Number for Pipeline Cost

When every operation draws from the same pool, the cost of a pipeline is the sum of its operations in a single unit. Extract data from a PDF, transform an image, generate a report — the total cost is visible in one place, in one currency.

This matters for two conversations that come up in every organization:

"What does it cost to onboard a new client?" If your pipeline processes client materials (intake documents, product images, branded reports), you can calculate the credit cost of the full onboarding flow and factor it into your pricing. No reconciliation across vendors.

"Where are we spending the most?" Usage analytics across all operations share the same unit. You can see that 60% of your credits go to extraction and 30% to document generation without normalizing across different billing models.

Alerts That Actually Mean Something

With one pool, usage alerts map to your actual concern: total processing budget. An 80% alert means 80% of your total capacity is consumed — regardless of which operations consumed it. No more cross-referencing three dashboards to figure out if you have a real problem or just a spike in one service.

Real Workflow Scenarios

The difference between per-service billing and unified credits shows up most clearly in concrete workflows. Here are three that represent common patterns.

Scenario 1: Monthly Client Reporting

An agency generates monthly reports for 15 clients. Each report involves:

Extracting financial data from uploaded bank statements and invoices (Document Extraction)
Generating a branded PDF report with tables, charts placeholder images, and executive summary (Document Generation)
Creating a social-ready summary card for each client's internal Slack channel (Image Generation)

With per-service billing, the agency manages three vendor relationships and three budgets. A client who sends 50-page statements instead of 10-page summaries blows the extraction budget without affecting the other two. The agency pays overage on extraction while their image generation credits sit unused.

With unified credits, the entire pipeline — extraction, document generation, image generation — draws from one pool. A heavy-extraction month just means fewer credits remain for other operations. The total spend is the same as long as the total volume stays consistent.

Scenario 2: E-Commerce Product Pipeline

An e-commerce platform onboards new products daily. Each product requires:

Extracting product specifications from supplier data sheets (Document Extraction)
Transforming and optimizing product images for web, mobile, and marketplace formats (Image Transformation)
Generating product listing cards with standardized layout and branding (Image Generation)
Generating a product comparison spreadsheet for internal review (Sheet Generation)

Four operations, and the volume of each varies wildly. A product with 12 images and a simple spec sheet is image-heavy. A product with complex technical specifications but one hero image is extraction-heavy.

Per-service billing forces the platform to provision for the worst case in each category. Unified credits let the total budget absorb the variance naturally.

Scenario 3: Compliance Document Processing

A financial services team processes compliance documents. Quarterly, they:

Extract data from hundreds of regulatory filings (Document Extraction)
Convert reference documents to markdown for internal knowledge base (Document to Markdown)
Generate compliance summary reports with standardized formatting (Document Generation)
Create audit-ready spreadsheets with extracted data (Sheet Generation)

The volume of regulatory filings varies quarter to quarter. A year-end quarter might have 3x the filings of a typical quarter. Per-service billing requires either massive over-provisioning or accepting quarterly overage charges. Unified credits scale with the actual work.

The Math: Per-Service vs. Unified

Consider a mid-size team with this monthly content processing profile:

Typical month:

500 pages of document extraction
2,000 image transformations
200 generated documents
100 generated images

Heavy extraction month (quarterly reporting):

1,500 pages of document extraction
1,000 image transformations
400 generated documents
50 generated images

With per-service billing, you either:

Commit high across all categories to handle peak months, wasting 30-50% of your committed capacity in typical months
Commit to typical volumes and pay overage rates during peak months, often at 1.5-2x the committed rate
Go fully on-demand across all vendors, paying the highest per-unit rate everywhere

With unified credits, you commit to a total pool sized for your average month plus a buffer. The heavy-extraction month draws more extraction credits and fewer image credits. The total stays within the pool. No waste, no overage, no reconciliation.

The exact credit costs for each operation type are documented at /docs/credits-and-pricing.

Financial Planning with a Single Pool

Unified credits change the financial planning conversation from "how much of each service do we need?" to "how much processing do we need?" That is a simpler question with a more stable answer.

Quoting Client Work

Agencies that build content pipelines for clients need to quote a price for the work. With per-service billing, the quote requires estimating each operation separately:

"We expect 200 pages of extraction at $X per page"
"About 500 image transformations at $Y per transformation"
"30 generated reports at $Z per document"

If any estimate is wrong, the margin on the engagement shifts. And estimates are always wrong — the question is by how much.

With unified credits, the quote is simpler: "This pipeline consumes approximately N credits per run. We run it M times per month. Total monthly cost: N * M credits." The per-operation breakdown still exists for internal analysis, but the client-facing number is a single figure that absorbs the variance.

Forecasting Spend

Finance teams that need to forecast annual processing costs face the same problem at a larger scale. Per-service billing requires forecasting each operation category independently, then summing. Each forecast carries its own error margin. The errors compound.

With unified credits, the forecast is one number: total credits consumed per year. You can still break it down by operation for capacity planning, but the financial commitment is a single line item. The error margin on one forecast is smaller than the compounded error margin on three independent forecasts.

Per-Project Cost Attribution

For teams that run multiple projects from one account, unified credits paired with per-project usage tracking give you clean cost attribution without the overhead of separate vendor accounts per project.

An agency running 10 client projects does not need 10 OCR accounts, 10 image processing accounts, and 10 PDF generation accounts. One account, one credit pool, and per-project API keys give them usage breakdowns by client while maintaining the billing simplicity of a single subscription.

Why This Is Hard to Retrofit

Per-service billing is not a deliberate choice by most vendors. It is the natural consequence of building a point solution. An OCR company charges for OCR. An image CDN charges for transformations. A PDF generator charges for documents. Each pricing model is perfectly rational for the service it covers.

The problem only becomes visible when your workflow spans services. And by that point, switching costs are high — you have integration code for each vendor, team members who know each dashboard, and budget processes built around the existing billing structure.

Unified billing requires that a single platform covers all the operations in the pipeline. It is not something you can bolt on across vendors. No amount of billing aggregation fixes the fundamental issue: each vendor sells capacity in their own unit, and those units are not fungible.

This is one of the reasons we built Iteration Layer as a multi-API platform rather than a point solution. The credit system is not a billing feature layered on top — it is a consequence of all operations sharing the same infrastructure, the same auth, and the same account.

What Unified Credits Do Not Fix

Unified credits solve the billing fragmentation problem. They do not make a bad API good.

If the extraction quality is poor, unified billing will not help. If image transformation is slow, a shared credit pool does not make it faster. The API quality has to stand on its own. Credits are the billing layer — the operations underneath still need to be accurate, fast, and well-documented.

Unified credits also do not replace the need to understand your costs per operation. You should still know that extraction costs X credits per page and document generation costs Y credits per document. The difference is that this understanding lives in one system instead of three, and the implications are simpler: you have N credits, and each operation subtracts from the same pool.

For the exact cost per operation, see our credits and pricing documentation.

When Per-Service Billing Actually Makes Sense

Unified credits are not universally better. They are better for pipelines. If your use case is genuinely single-operation, per-service billing might serve you well.

If you only extract data from documents and never generate, transform, or convert anything, a dedicated OCR service with per-page pricing gives you a clear cost model with no ambiguity. You know what you pay, you know what you get, and there is no cross-operation variance to manage.

The same applies if you only transform images, or only generate PDFs. Point solutions with operation-specific pricing are optimized for that operation. They may offer deeper features, better per-unit rates at scale, or specialized tooling that a multi-operation platform does not.

The trade-off shows up the moment you add a second operation to your workflow. That is when per-service billing starts creating the overhead described above. And in practice, most content processing workflows involve at least two operations — extraction followed by generation, or transformation followed by generation, or ingestion followed by transformation and then generation.

The question is not "are unified credits better?" but "does my workflow span multiple operations?" If the answer is yes — and it usually is — unified credits remove a category of complexity that has nothing to do with the content you are processing.

Who Benefits Most

Unified credits matter more in some contexts than others.

Agencies managing multiple client projects benefit the most. Each client project has a different operational mix, and the agency cannot predict which client will send what kind of work next month. A shared credit pool across all projects — with per-project usage tracking — means the agency commits to total processing volume, not per-client, per-operation volume.

Teams with seasonal or variable workloads benefit because the peak-to-trough ratio in any single operation can be dramatic, even when total processing volume stays relatively stable. Unified credits smooth the variance.

Early-stage products benefit because the operational mix is still being discovered. You do not know yet whether your product will be extraction-heavy or generation-heavy. Committing to per-service tiers is a premature optimization that often turns into a premature constraint.

Operations teams building automations benefit because workflows in tools like n8n or Make chain multiple operations together. The cost of an automation is the sum of its steps, and that sum is much easier to calculate — and budget for — when every step draws from the same pool.

The Workflow Is the Product

Per-service billing is a natural fit for point solutions. If you only need OCR, buying OCR credits makes perfect sense. If you only need image transformation, per-transformation pricing is clear and fair.

But most content processing work is not a single operation. It is a pipeline: ingest, transform, generate. The moment your work spans two operations, per-service billing starts working against you. By the time it spans three or four, you are spending real time and money on billing reconciliation that has nothing to do with the content you are processing.

Unified credits are not a marketing feature. They are a structural consequence of building a platform where operations compose. When all operations share the same infrastructure, the same auth, and the same account, it would be strange to bill them separately.

One pool. Every format. Spend where the work is.

Get Started

Check the credits and pricing documentation for per-operation rates. Every Iteration Layer account — including the free tier — uses a single credit pool across all APIs: Document Extraction, Image Transformation, Image Generation, Document Generation, Sheet Generation, and Document to Markdown. Sign up, get an API key, and start building. No credit card required.

Self-Hosted vs. Managed Document Processing: When to Build and When to Buy

Iteration Layer — Mon, 20 Apr 2026 23:34:04 +0000

The Build-vs-Buy Question Nobody Answers Honestly

Every developer who needs to process documents — extract data from PDFs, generate reports, transform images, convert between formats — eventually faces the same decision: build the pipeline yourself or pay someone else to run it.

The internet is full of advice on this, and most of it is dishonest. Vendor blogs claim self-hosting is a maintenance nightmare. Open-source advocates claim managed services are overpriced rent-seeking. Neither side acknowledges the real picture: both approaches work, both have legitimate advantages, and the right choice depends on factors specific to your situation.

This guide lays out those factors. No "our way is always better." No hand-waving over real tradeoffs. Just a framework for making the decision with clear eyes.

What We Mean by "Document Processing"

Before comparing approaches, it helps to define the scope. "Document processing" in this context covers:

Extraction — pulling structured data from unstructured documents (invoices, contracts, receipts, forms)
Generation — producing formatted documents from structured data (PDFs, XLSX, DOCX, EPUB)
Transformation — converting, resizing, compressing, or manipulating images and documents
Conversion — turning documents from one format to another (PDF to Markdown, DOCX to PDF, images to text via OCR)

Most real-world pipelines combine two or more of these. An invoice processing workflow extracts data, then generates a summary report. A content pipeline transforms images, then generates a formatted document. The combination matters because it affects how much integration work each approach requires.

The Self-Hosted Stack

The self-hosted approach means running open-source tools on your own infrastructure. The typical stack looks something like:

OCR/Extraction: Tesseract, Kreuzberg, PaddleOCR, or a local LLM with document understanding
PDF Generation: Puppeteer/Playwright (headless browser), WeasyPrint, or wkhtmltopdf
Image Processing: Sharp (Node.js), Pillow (Python), ImageMagick, or libvips
Spreadsheet Generation: openpyxl (Python), ExcelJS (Node.js), Apache POI (Java)
Format Conversion: LibreOffice in headless mode, Pandoc, or specialized converters

Each tool is battle-tested and widely used. The open-source ecosystem for document processing is mature. These are not experimental projects — they have years of production use behind them.

Where Self-Hosting Wins

Zero marginal cost. After the initial setup and infrastructure investment, each additional document costs only compute time. If you process millions of documents per month, the per-document cost of self-hosting approaches zero. For high-volume, predictable workloads, the economics are hard to beat.

Full control over every parameter. Need a specific Tesseract language model? A custom ImageMagick policy? A Puppeteer flag that no managed service exposes? Self-hosting gives you access to every configuration option, every flag, every environment variable. No vendor decides what you can and cannot configure.

No vendor dependency. Your pipeline runs on your infrastructure, using open-source tools you can fork if needed. No API key expiration, no pricing changes, no terms-of-service updates, no vendor going out of business. The tools exist independent of any company.

Data never leaves your network. For organizations with strict data residency or security requirements — government agencies, healthcare providers, financial institutions — keeping documents on-premises may be a hard requirement, not a preference. Self-hosting satisfies this by default.

Offline operation. If your pipeline needs to run in air-gapped environments, on edge devices, or in locations with unreliable internet, self-hosting is the only option. A managed API requires network connectivity by definition.

Where Self-Hosting Hurts

Integration is the real cost. The individual tools work. The pain lives in the glue code between them. Tesseract gives you text; you need to parse it into structured fields. Sharp gives you a buffer; you need to handle format detection, error cases, and memory limits. Puppeteer gives you a PDF; you need to manage the Chrome process lifecycle, handle timeouts, and clean up zombie processes.

Each tool has its own API surface, its own error format, its own quirks. The code connecting them — the format conversions, the retry logic, the error handling — is the most fragile part of the system. It's also the part that nobody writes tests for, because it's "just glue."

Edge cases compound. OCR works on clean scans. It struggles with photographed documents, skewed pages, low contrast, handwriting, mixed languages, and unusual fonts. Image processing works on standard formats. It breaks on CMYK TIFFs, animated GIFs with transparency, corrupted headers, and images that claim to be JPEG but are actually PNG.

Each tool has its own category of edge cases. When you chain multiple tools together, the edge cases multiply. A malformed PDF that Tesseract handles gracefully might produce output that breaks your parsing regex, which produces data that crashes your report generator. Debugging these failures across tool boundaries is time-consuming.

Infrastructure overhead is ongoing. Self-hosting is not a one-time setup cost. It's an ongoing commitment:

Keeping dependencies updated (security patches, new versions)
Scaling compute to match load (headless Chrome is memory-hungry)
Monitoring for failures (zombie processes, disk space, memory leaks)
Managing Docker images (base image updates, dependency conflicts)
Handling platform-specific issues (libvips compiled without HEIF support, Tesseract without the language data you need)

For a team with dedicated DevOps capacity, this is manageable. For a small team where the same person writes features and manages infrastructure, it's a significant ongoing tax.

Time-to-value is measured in days or weeks. Getting Tesseract to extract structured data from a specific document type requires training data, configuration tuning, and custom parsing logic. Getting Puppeteer to generate consistent PDFs requires handling font loading, CSS rendering differences, and page break behavior. Each tool's learning curve is separate.

A developer who has never used these tools should budget days to weeks for a production-ready pipeline, depending on complexity. That's not a criticism — it's a realistic assessment of the work involved.

The Managed API Approach

The managed approach means sending documents to an API and getting results back. Instead of running Tesseract, you call an extraction endpoint. Instead of managing Puppeteer, you call a generation endpoint. The vendor handles infrastructure, scaling, edge cases, and updates.

Where Managed Services Win

Time-to-value in minutes. Sign up, get an API key, make a request. The first working extraction, generation, or transformation happens in the time it takes to read the API docs and write a fetch call. No Docker setup, no dependency installation, no configuration tuning.

For prototyping, this speed difference matters. You can validate whether a document processing pipeline solves your business problem before investing in infrastructure. If the approach doesn't work, you've lost an afternoon, not a sprint.

Edge cases are the vendor's problem. A managed extraction service has processed millions of documents. The malformed PDF that would take your team two days to debug is a known edge case with a fix already deployed. The CMYK TIFF that crashes your Sharp pipeline is handled transparently.

This is not theoretical. Every document processing vendor maintains a growing library of fixes for document formats, encoding issues, font rendering bugs, and format-specific quirks. When you self-host, you maintain your own library of fixes. When you use a managed service, you inherit the vendor's.

No infrastructure to maintain. No Docker images to update. No memory limits to tune. No zombie processes to clean up. No scaling decisions to make. The API handles one request the same way it handles ten thousand. The operational burden is genuinely zero on your side.

Consistent API surface across operations. If you need extraction, generation, and transformation, a managed platform gives you one auth mechanism, one error format, one response structure, and one billing system. Self-hosting gives you three different tools with three different interfaces. The integration cost of adding a second operation to a managed pipeline is trivial compared to adding a second self-hosted tool.

Where Managed Services Hurt

Per-request cost at scale. Every API call costs money. At low volumes, the cost is negligible — far less than the engineering time to self-host. At high volumes, the math changes. If you process hundreds of thousands of documents per month, the API costs may exceed the infrastructure and engineering costs of self-hosting.

The crossover point depends on the specific service, the document complexity, and your team's engineering capacity. But it exists, and honest evaluation requires acknowledging it.

Vendor dependency is real. Your pipeline depends on a third-party service. If the vendor changes pricing, deprecates an endpoint, experiences downtime, or goes out of business, your pipeline is affected. You can mitigate this with abstraction layers and fallback logic, but the dependency exists.

Feature ceiling. A managed API exposes the features the vendor chose to build. If you need a specific configuration option, a custom processing step, or behavior that the API doesn't support, you're blocked. You can request it, but you can't implement it yourself.

Network latency. Every request requires an HTTP round trip. For bulk processing where you're making thousands of requests, the cumulative latency adds up. Most managed services offer async/webhook-based processing for large workloads, but the latency is inherently higher than local processing.

Data leaves your network. Your documents travel to the vendor's servers for processing. For many use cases this is fine — the data is not sensitive, or the vendor's security practices are adequate. For some use cases — classified documents, medical records, certain financial data — it may be a hard constraint.

This is where the vendor's infrastructure location and data handling practices matter. A service that processes in-memory with zero retention on EU infrastructure is different from one that stores documents on US servers. But even with the strongest guarantees, the data does leave your network during processing.

The Decision Framework

The right choice depends on a handful of concrete factors. Not opinions, not ideology — factors you can evaluate for your specific situation.

Factor 1: Volume and Growth Trajectory

Monthly volume	Likely winner	Why
Under 1,000 documents	Managed	Engineering time to self-host far exceeds API cost
1,000 - 50,000 documents	Depends	Evaluate based on other factors below
Over 50,000 documents	Evaluate carefully	API costs may exceed infrastructure costs; run the numbers

Volume alone doesn't determine the answer. A team processing 100,000 documents with two DevOps engineers has different economics than a solo developer processing 100,000 documents. But volume is the first variable to pin down because it bounds the cost comparison.

Factor 2: Pipeline Complexity

How many different operations does your pipeline chain together?

Single operation (extraction only, or generation only): Self-hosting is simpler because you manage one tool. The integration tax is low.
Two operations (extract then generate, or transform then generate): The integration cost doubles. You now manage two tools, two error formats, two deployment configurations, and the glue code between them.
Three or more operations: Integration complexity grows faster than linearly. Each new tool adds its own failure modes, and the failure modes interact across tool boundaries. A managed platform with a consistent API surface becomes increasingly attractive.

The complexity factor often surprises teams. Adding a second self-hosted tool is not twice the work — it's the original work plus the integration work, which is often larger than either tool's setup alone.

Factor 3: Team Composition

Team	Self-host viability	Managed viability
Full-stack with DevOps capacity	High	High
Small dev team, no dedicated ops	Low-Medium	High
Operations/automation builders, limited coding	Very low	High
Solo developer	Low (unless domain expert)	High

Be honest about this one. "We could self-host" is different from "we have the ongoing capacity to maintain a self-hosted pipeline." The initial setup is a one-time cost. The maintenance — updating dependencies, debugging edge cases, scaling infrastructure — is indefinite.

Factor 4: Data Sensitivity

Data type	Self-host advantage
Public or low-sensitivity data	Minimal — managed is fine
Standard business documents (invoices, reports)	Low — managed services with EU hosting and zero retention are adequate for most compliance frameworks
Regulated data (healthcare, financial, classified)	Significant — on-premises or air-gapped may be required
Government/defense with data sovereignty requirements	Decisive — self-hosting is likely mandatory

For the middle categories, the question is not "is managed acceptable?" but "does this specific managed service meet our specific compliance requirements?" A vendor that processes in EU data centers with zero file retention and a Data Processing Agreement satisfies most EU regulatory frameworks. A vendor that stores documents on US servers does not.

Factor 5: Time Constraints

If you need a working pipeline this week, self-hosting a multi-tool stack is unlikely. If you have a quarter to build and optimize, self-hosting becomes viable.

This factor is often underweighted. The business need that drives the pipeline doesn't pause while you configure Tesseract and debug Puppeteer. A managed service that works today and a self-hosted pipeline you build later is a valid strategy — and often the most pragmatic one.

The Decision Matrix

Putting the factors together:

Scenario	Recommendation
Low volume, multi-step pipeline, small team	Managed — the engineering cost of self-hosting far exceeds API cost
High volume, single operation, DevOps capacity	Self-host — the per-document savings justify the infrastructure investment
High volume, multi-step pipeline, large team	Hybrid — self-host the high-volume single operation, managed for the rest
Regulated data, air-gapped environment	Self-host — no alternative
Prototype or MVP validation	Managed — validate the approach before investing in infrastructure
Operations team automating workflows	Managed — self-hosting requires engineering capacity they don't have

The hybrid approach deserves emphasis. It's not all-or-nothing. A team might self-host image transformation (high volume, single tool, well-understood) while using a managed API for document extraction (complex, edge-case-heavy, lower volume). The approaches are not mutually exclusive.

The Hidden Costs People Forget

Both approaches have costs that don't appear in the initial comparison.

Self-Hosting Hidden Costs

Opportunity cost. Every hour spent debugging a Puppeteer timeout or an ImageMagick policy conflict is an hour not spent on your product. For small teams, this is the most expensive cost and the hardest to quantify.
Recruitment/knowledge cost. When the person who built the pipeline leaves, the next person inherits a custom system with custom workarounds. Documentation helps, but document processing pipelines accumulate tribal knowledge about edge cases.
Security patching. Open-source tools have CVEs. Tesseract, ImageMagick, Puppeteer, and their dependencies all require security monitoring and updates. This is ongoing and non-optional.
Scaling surprises. A pipeline that works for 100 documents per day may fail at 10,000. Headless Chrome is memory-hungry. ImageMagick can consume unbounded memory on certain inputs. Scaling requires load testing, resource limits, and capacity planning that wasn't part of the initial setup.

Managed Service Hidden Costs

Vendor lock-in friction. Even with clean API abstractions, switching vendors takes engineering time. Request/response formats differ. Error handling differs. Behavior on edge cases differs. The switching cost is not zero.
Rate limiting at inconvenient times. Most managed services have rate limits. If your processing load is spiky — month-end reporting, seasonal catalog updates — you may hit limits precisely when you need the service most.
Feature gaps you discover late. You don't know what the API can't do until you need it to do it. Discovering a missing feature after building your pipeline around the service is expensive.
Billing unpredictability. If your volume is unpredictable, your bill is unpredictable. Managed services with per-request pricing pass volume variance directly to your costs.

A Realistic Comparison for Three Common Pipelines

Pipeline 1: Invoice Data Extraction

The task: Extract vendor name, date, line items, and total from PDF invoices. Hundreds per month.

Self-hosted approach: Tesseract for OCR, custom regex or LLM for field extraction, Python script to orchestrate. Setup: 2-3 days. Ongoing maintenance: 2-4 hours/month debugging extraction failures on unusual invoice formats.

Managed approach: Call an extraction API with a schema defining the fields. Setup: 1 hour. Ongoing maintenance: near zero — new invoice formats are the vendor's problem.

Verdict at this volume: Managed. The engineering time saved in the first month exceeds a year of API costs.

Pipeline 2: Product Image Processing for E-Commerce

The task: Resize, compress, convert format, and optionally remove backgrounds for product images. Tens of thousands per month.

Self-hosted approach: Sharp or libvips behind a small service. Setup: 1 day (Sharp is well-documented). Ongoing maintenance: low — image processing is a well-understood problem with few surprises.

Managed approach: Call a transformation API with an operations array. Setup: 30 minutes. Ongoing: API cost scales linearly with volume.

Verdict at this volume: Depends on volume sensitivity. At 5,000 images/month, managed is simpler and the cost is modest. At 50,000 images/month, the per-image API cost adds up, and Sharp is stable enough that self-hosting is low-risk. At 500,000 images/month, self-hosting almost certainly wins on cost.

Pipeline 3: Monthly Financial Reporting

The task: Extract data from supplier invoices, aggregate by vendor, generate a formatted XLSX with multiple tabs, and produce a summary PDF. Hundreds of documents per month, output is a handful of reports.

Self-hosted approach: Tesseract + custom parsing for extraction, openpyxl for XLSX, Puppeteer or WeasyPrint for PDF. Three tools, three deployment configurations, and significant glue code. Setup: 1-2 weeks. Ongoing maintenance: 4-8 hours/month across the three tools.

Managed approach: Extraction API for parsing, sheet generation API for XLSX, document generation API for PDF. Three API calls using the same auth, same credit pool, same error format. Setup: 2-3 hours. Ongoing: API cost (modest at this volume) and near-zero maintenance.

Verdict: Managed. The three-tool self-hosted pipeline has high integration complexity and significant ongoing maintenance. The managed version uses one vendor with a consistent interface. The cost differential at hundreds of documents per month strongly favors the managed approach.

The Hybrid Strategy

For teams in the "it depends" range, the most pragmatic approach is often hybrid: start managed, observe your actual usage patterns, then selectively self-host the operations where it makes economic sense.

This works because:

You validate the pipeline before investing in infrastructure. If the business case doesn't pan out, you haven't built and maintained a self-hosted stack for nothing.
You identify which operations are worth self-hosting. Maybe extraction is complex and edge-case-heavy (keep managed), but image resizing is straightforward and high-volume (self-host).
You reduce risk. A managed service handles the operations where you lack expertise. Self-hosting handles the operations where you have confidence and volume justifies the investment.

The key is treating the decision as reversible and incremental, not as a one-time architectural commitment.

What to Look for in a Managed Service

If you decide managed is the right approach — at least for some of your pipeline — the evaluation criteria matter:

Data handling. Where are documents processed? Is there data retention? Is processing in-memory or stored to disk? Is a Data Processing Agreement available?
Infrastructure location. For EU-facing products, EU-hosted processing avoids the GDPR complications of transatlantic data transfers.
API consistency. If you need multiple operations (extraction + generation + transformation), does the service offer a consistent interface across all of them? Or are you integrating with what amounts to multiple separate products under one brand?
Pricing model. Per-request, per-page, per-MB, or credit-based? Is the pricing predictable for your workload? Are there hidden fees (bandwidth, storage, overage)?
Composability. Can the output of one operation feed directly into the input of another without format conversion or middleware? This is the difference between a platform and a collection of APIs.

Making the Call

The build-vs-buy decision for document processing is not about which approach is universally better. It's about which approach is better for your specific volume, team, timeline, data sensitivity, and pipeline complexity.

Self-hosting wins when you have high volume, simple pipelines, DevOps capacity, and strict data requirements. Managed wins when you have complex multi-step pipelines, limited ops capacity, and value time-to-delivery over per-unit cost optimization.

Most teams fall somewhere in between. That's where the hybrid approach — start managed, selectively self-host — is the honest recommendation. Not because we're hedging, but because document processing pipelines evolve. Your volume changes. Your requirements change. Your team changes. The right architecture today might not be the right architecture in a year.

Make the decision that gets you to production fastest with acceptable cost and risk. Revisit it when the facts change.

Where Iteration Layer Fits

We built Iteration Layer as a managed document processing platform with composable APIs — extraction, generation, transformation, and sheet generation, all sharing one auth token, one credit pool, and one API style. Everything runs on EU infrastructure with zero file retention.

For teams where managed is the right choice, we think the composability and unified platform matter more than any individual feature. For teams where self-hosting makes sense for part of the pipeline, our APIs can handle the parts where managed wins — the complex, edge-case-heavy operations — while you self-host the rest.

The documentation covers every API. Sign up for a free account — no credit card required — and decide for yourself whether the tradeoffs work for your situation. We'd rather you make an informed decision than a pressured one.

Upscale, Resize, and Transform Images Inside Claude and Cursor with MCP — No Code Required

Iteration Layer — Fri, 27 Mar 2026 20:26:08 +0000

Low-Res Images, High-Res Problems

You're reviewing a pull request and notice the product images are 300x300. The design spec says 1200x1200. The originals are gone — the supplier sent what they sent, and nobody kept higher-resolution versions.

You could download the images, run them through a Python upscaling script, install the dependencies, wait for the model to process, and re-upload. Or you could ask your AI assistant to do it in one sentence.

MCP makes this possible. The Model Context Protocol lets AI assistants like Claude Desktop and Cursor call external APIs as tools. Connect the Image Transformation API as an MCP server, and your assistant can upscale, resize, crop, and convert images directly from a conversation. Describe what you need, it calls the API, you get the result.

No scripts. No dependencies. No context switching.

What MCP Is

Model Context Protocol is an open standard that gives AI assistants the ability to discover and call external services. Think of it as a plugin system — you register a tool, and the assistant uses it when your request matches.

When you connect the Image Transformation API as an MCP server, your assistant gains a full suite of image operations: upscaling low-resolution images at 2x, 3x, or 4x, resizing to exact dimensions, cropping, and converting between formats. All from a single MCP server.

The upscaling capability is not interpolation. The API uses an AI super-resolution model that generates actual detail — texture, edges, fine patterns — that didn't exist in the original pixels. A blurry 500x500 image at 4x becomes a sharp 2000x2000 image with real visual information.

Setting Up in Claude Code

Claude Code supports MCP servers natively. Add the Iteration Layer server with a single command:

claude mcp add iterationlayer --transport http https://api.iterationlayer.com/mcp

The first time you use an Iteration Layer tool, a browser window opens for OAuth authentication. Log in, authorize access, and you're connected. No API keys to manage.

To verify the server is available, start a conversation and ask Claude Code what MCP tools it has access to. You should see transform_image listed among the available tools.

Setting Up in Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "iterationlayer": {
      "type": "http",
      "url": "https://api.iterationlayer.com/mcp"
    }
  }
}

Save and restart. The Image Transformation tool is now available in your Cursor AI conversations. Authentication works the same way — OAuth in the browser on first use.

Using It Conversationally

Upload an image and describe what you need:

"Upscale this product image to 4x resolution."

The assistant calls the Image Transformation API with an upscale operation at factor 4, and returns the upscaled image. A 500x500 input becomes 2000x2000 with generated detail — not blurred pixels.

"This logo is too small for the print layout. Upscale it to 2x."

The assistant uses a 2x factor, doubling the resolution while preserving the logo's sharpness.

"Upscale this photo to 3x for the hero banner."

Three times the resolution. The model generates texture and edge detail that makes the image hold up at the larger size.

More MCP Conversations

The conversational pattern scales beyond single-image requests. Here are a few more interactions that show what's possible.

Comparing factors side by side:

"Upscale this photo at 2x and 4x so I can compare the results."

The assistant makes two separate API calls — one with factor 2, one with factor 4 — and returns both images. You compare them in the conversation and pick the one that balances file size and quality for your use case.

Upscaling a batch of icons:

"I have these five SVG-exported PNGs at 64x64. Upscale each one to 4x for the app store assets."

The assistant processes each image individually through the API. Five calls, five results, all in one conversation thread. No script, no loop, no dependencies to install.

Chaining multiple operations:

Because the Image Transformation MCP server handles upscaling, resizing, cropping, and format conversion in a single server, you can chain operations naturally:

"Upscale this image to 3x, then convert it to WebP and resize it to exactly 1200x800."

The assistant chains the operations through the Image Transformation API — upscale, format conversion, and resize — all in one conversation.

"This supplier photo is 400x300. Upscale it to 4x, then crop it to a square and compress it under 200KB."

The assistant runs the upscale (producing a 1600x1200 image), then chains a crop and a target-size compression. What would normally be three scripts or a multi-step CLI pipeline becomes one sentence.

When to Upscale

Legacy images. Old product catalogs, archived marketing materials, images from systems that stored thumbnails as the "original." The high-res version doesn't exist. AI upscaling is the only way to recover usable resolution.

Supplier-provided images. E-commerce teams deal with this constantly. Suppliers send images at whatever resolution they have — often 300x300 or 400x400. Marketplaces require 1000x1000 minimum. Traditional upscaling produces blurry results. AI upscaling generates the detail needed to meet the spec.

Print preparation. An image looks fine on screen at 72 DPI but falls apart at 300 DPI for print. Upscaling 2x or 4x gives you enough resolution for print-quality output without visible artifacts.

User uploads. Users upload whatever they have — phone screenshots, cropped thumbnails, profile pictures from 2015. If your application needs a larger version, AI upscaling is better than showing a blurry stretched image.

Choosing a Factor

The API supports three upscaling factors. Each one multiplies both dimensions:

2x — a 500x500 image becomes 1000x1000 (4x the pixels). Good for images that are close to the target resolution but need a bump.
3x — a 500x500 image becomes 1500x1500 (9x the pixels). A solid middle ground for most use cases.
4x — a 500x500 image becomes 2000x2000 (16x the pixels). Maximum enhancement. Best for images that are significantly below the target resolution.

Higher factors mean more generated detail. The model is filling in information that wasn't in the original, so there's a practical limit — upscaling a 50x50 icon to 4x won't produce a photo-realistic 200x200 image. For best results, start with the smallest factor that gets you to the resolution you need.

What Happens Under the Hood

When the assistant calls the API, it sends a POST request to https://api.iterationlayer.com/image-transformation/v1/transform with your image and the desired operations. The request body specifies the file and a list of operations — for example, { "file": {"type": "url", "name": "image.jpg", "url": "..."}, "operations": [{"type": "upscale", "factor": 4}] }. The AI model processes the image, generating new pixels based on patterns it learned from millions of high-resolution images.

You can chain multiple operations in a single request — upscale, then resize, then convert to WebP — and the API processes them in sequence. This is what makes the single MCP server so versatile: one connection gives you the full image transformation pipeline.

Quality Expectations

AI upscaling is not magic, and setting expectations correctly matters. The model works best on photographs and natural images — textures, skin, hair, fabric, foliage. These have predictable patterns the model has learned to extend.

It works well on product photography. Supplier images that arrive at 400x400 upscale to 1600x1600 with believable detail. Edges stay sharp, product surfaces gain texture, and the result passes visual inspection at marketplace-required dimensions.

It works less well on text and sharp geometric shapes. A screenshot with small text at 300x200 upscaled to 4x will have smoother text, but it won't match the crispness of a native-resolution render. For images with prominent text, 2x is usually the practical ceiling before artifacts become noticeable.

Icons and logos fall somewhere in between. Simple shapes with flat colors upscale cleanly. Detailed logos with fine lines may gain subtle softness at higher factors. If you need pixel-perfect scaling for vector-origin artwork, re-exporting from the source SVG at the target resolution is always better — but when the source file is gone, 2x upscaling is a reasonable recovery option.

MCP vs Direct API Calls

MCP is built for ad-hoc work. You need one image transformed, right now, without writing code. The assistant handles the API call, the file encoding, the response parsing. You describe, it delivers.

For production pipelines — upscaling product images during catalog import, processing user uploads on the fly, batch-enhancing legacy image libraries — use the API directly. The request body is JSON. Any language that can make an HTTP POST can transform images.

The two approaches fit different moments. Prototype in conversation with MCP, then move the pattern into your codebase when it becomes a recurring workflow.

Common Pitfalls

Upscaling already-compressed JPEGs. Heavy JPEG compression creates visible block artifacts. Upscaling amplifies those artifacts rather than removing them. If the source image is heavily compressed, the upscaled version will look better than bicubic interpolation, but the compression artifacts will still be visible. Start from the highest-quality source you have.

Using 4x when 2x is enough. Higher factors produce larger files and longer processing times. If you need a 1000x1000 image and your source is 600x600, 2x gives you 1200x1200 — more than enough. Save 4x for cases where the source is genuinely small relative to the target.

Expecting upscaling to fix motion blur or focus issues. AI upscaling generates detail from patterns, but it cannot recover information that was never captured. A blurry photo becomes a larger blurry photo. The model may sharpen some edges, but fundamental focus problems remain.

Get Started

Sign up for a free account at iterationlayer.com — no credit card required. Run the claude mcp add command above, authenticate in the browser, and transform your first image from your next Claude Code or Cursor conversation.

The docs cover the full API reference — request format, response format, file size limits, supported operations, and factor options.