Image to Image Command Line Tool
Overview
Convert images between formats and resize, crop, or rotate them from your terminal or shell scripts. The image2image command sends your input to PDFCrowd's servers and saves the result locally.
Installation
Install the command-line client with pip, or see other installation options.
python -m pip install pdfcrowd-cli
Quick Start
You can run the examples below without account setup. The CLI uses demo credentials unless you have configured your own API credentials. Update the input URLs and filenames as needed.
Commands use POSIX-shell syntax, as in Bash or Zsh, and save results in the current directory.
Convert a URL
Fetch an image from its URL and save the result locally:
image2image --output-format=jpg \ --output logo.jpg \ https://your-server.com/logo.png
Convert a File
Upload an existing logo.png file and save logo.jpg:
image2image --output-format=jpg \ --output logo.jpg \ logo.png
Configure a Conversion
Choose an Input
Supply one URL or local file. Use - to read bytes from stdin, including input
piped from another program. Remote URLs must be reachable from PDFCrowd's servers;
upload a local file or send its bytes for input on localhost or a private network.
See Conversion Input
for the supported forms.
The source image format is detected automatically. Each conversion accepts one image.
Read Bytes from Stdin
Read logo.png through stdin and save logo.jpg:
image2image --output-format=jpg \ --output logo.jpg \ - < logo.png
Add Conversion Settings
Add options before the input. Command-line options override saved conversion defaults.
image2image --output-format=png \ --resize=400x400 \ --output thumbnail.png \ scan.png
Image operations change the source image; canvas settings control the output area and image placement.
| Purpose | Options |
|---|---|
| Resize or rotate | --resize, --rotate |
| Crop or remove solid-color borders | --crop-area, --remove-borders |
| Image resolution for layout | --dpi |
| Image format | --output-format |
| Canvas dimensions and margins | --canvas-size, --canvas-dimensions, --margins, --orientation |
| Image placement and background | --print-canvas-mode, --position, --canvas-background-color |
With an explicit canvas size, use --print-canvas-mode with "fit" to preserve the aspect ratio and fit the image inside the margins.
The "stretch" mode fills the area and can distort the image. The default mode does not scale the image to fit and can crop it.
Without an explicit size, margins add a border around the image.
See the command reference for all options and Configuration for saved defaults. For more tasks, browse the CLI examples.
Handle the Result
Choose an Output
The quick-start examples select JPEG. Use --output-format to choose PNG, WebP, or another supported format. The default is PNG; match the filename extension to your selected format. JPEG cannot retain transparency.
The examples save the result with
--output PATH.
The CLI replaces that file only after successful conversion, preserving an existing file
if conversion fails. Diagnostics go to stderr.
Omit --output or use --output - to send the result to stdout
for a pipe or shell redirection.
image2image refuses to send binary output directly to an interactive terminal.
Shell redirection opens or truncates its destination before the command runs and can leave
an empty or partial file on failure.
Handle Errors
Check the command's exit status before using its output: 0 means success and
a nonzero status means failure. In a shell script, $? immediately after the
conversion contains its status.
Service errors are written to stderr with the prefix PDFCrowd Error: and include
the status code, reason code, message, and documentation link when available.
These service codes differ from the command's process exit status.
See API status codes for service errors and
image2image help exit-codes for the process exit-code mapping.
Read Conversion Information
Add --print-output-size
to report the output size in bytes, or
--print-remaining-credit-count
to report the remaining credits after conversion.
Requested conversion information is printed to stderr, leaving stdout available for the result. See Output for all supported information flags.
Limits and Retries
Request rate and concurrency limits depend on your license. Control how quickly
your application submits conversions and how many it runs at once. A
429 response concerns request rate; a 430 response
concerns requests already in progress. The maximum upload size is 300 MB.
The CLI automatically retries a request once after an HTTP 502 or
503 response. Use --retry-count
to change the count, or set it to 0 to disable automatic retries.
Account for these retries when adding retries to a script or job runner.
Troubleshooting
Inspect a Conversion
Enable --debug-log and request
--print-debug-log-url.
This example saves the converted JPEG as response.body and prints the
debug-log URL to stderr:
image2image --print-debug-log-url \ --debug-log \ --output-format=jpg \ --output response.body \ https://your-server.com/logo.png
The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.
Common Problems
| Problem | Check |
|---|---|
| The image cannot be loaded | Check that the URL returns an image, rather than HTML or a login page, and is reachable from PDFCrowd's servers. For local files, check the path and read permissions. |
| The image is distorted or cropped | Check dimensions, crop settings and margins. Use "fit" with --print-canvas-mode when setting an explicit output size. |
| The result looks blurry | Check the source image's pixel dimensions and how much it is enlarged. Increasing DPI cannot recover missing detail. |
| Transparency is lost | JPEG does not support transparency. Select PNG and check whether the canvas background adds an opaque color. |
For help, contact support
with available diagnostics, the version from image2image --version,
and enough detail to reproduce the problem.