---
title: "Resize, crop, rotate, or convert an image"
method: POST
path: "/v1/image/transform"
tags: ["Utilities"]
---

# Resize, crop, rotate, or convert an image

`POST /v1/image/transform`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/image/transform`
- Auth: HTTP bearer

Pipeline image processor. Reads `input_path`, applies optional `crop` then
`resize` then `rotate_degrees`, and writes to `output_path` in the requested
`format` (png/jpeg/heic/webp/tiff — inferred from extension if omitted).
Pure format conversion (no transforms) is allowed.

## Request body

- ImageTransformRequest
  - `input_path` string, required: Absolute path to the source image.
  - `output_path` string, required: Absolute path for the transformed output.
  - `format` 'png' | 'jpeg' | 'heic' | 'webp' | 'tiff': Output format. Inferred from `output_path` extension when omitted.
  - `quality` number: Encoder quality (lossy formats). Default 0.9.
  - `crop` object
    - `x` integer, required
    - `y` integer, required
    - `width` integer, required
    - `height` integer, required
  - `resize` object: Provide at least one of `width`, `height`, `max_dimension`.
    - `width` integer
    - `height` integer
    - `max_dimension` integer
    - `fit` 'fill' | 'contain' | 'cover': Resize fit mode. Default `contain`.
  - `rotate_degrees` number: Counter-clockwise rotation in degrees.

## Response `200`

Transform result (output path, byte size, dimensions)

- ImageTransformResponse
  - `path` string, required
  - `bytes` integer, required
  - `width` integer, required
  - `height` integer, required

## Other responses

- `400`: Invalid request
- `404`: Input image not found
- `500`: Decode, encode, or write failed

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)