Solving image rotation issues: How our API handles exif orientation

How the API handles orientation

When processing requests, the uploaded image is opened and immediately passed through ImageOps.exif_transpose. That means if the source relies on EXIF metadata to say “this image should be displayed rotated,” the API applies that orientation before further work continues.

At a high level, the flow looks like this:

1. Input image opened
2. ImageOps.exif_transpose(...) applied
3. Image loaded and normalized for orientation
4. Mask generated
5. Output composed from the corrected orientation

This is exactly why the API usually behaves correctly with phone photos that depend on EXIF orientation, especially images coming from iPhone-style capture workflows.

Why rotated images still happen anyway

Even though the API normalizes EXIF orientation, rotation issues can still show up in real apps because orientation problems often happen before upload or after download. For example, one viewer may honor EXIF metadata while another ignores it. A preprocessing step may strip EXIF without baking the rotation into pixels. Or a frontend canvas export may create a new file that no longer behaves like the original.

In other words, the API can be doing the right thing and you can still observe a rotated result somewhere else in the product stack.

• The source file looks upright only because the viewer honors EXIF metadata
• Another app ignores EXIF and shows the raw pixel orientation
• An upstream step strips EXIF without baking the rotation into pixels
• A re-encode step rotates the pixels and also leaves stale orientation metadata
• A mobile or browser pipeline exports a different image than the one you think it sent
• A frontend canvas or preview layer displays the image differently than the saved file

Common symptoms

Rotation issues usually show up in one of these patterns:

• The original looks correct in Photos but wrong in another viewer
• The API output looks rotated only inside your app, not on disk
• An iPhone photo behaves differently after upload or compression
• HEIC input looks right locally but different after an upstream conversion
• The mask alignment looks correct, but your UI preview appears rotated

One very strong clue is this: if the API output looks correct when saved to disk and opened in a normal viewer, but wrong only inside your app, the issue is probably in the display layer rather than the API result.

Quick checklist

Before changing anything in production, walk through this:

1. First verify whether the rotated result is actually coming from the API or from your app viewer
2. Test the same file with a direct API request and save the output
3. Compare the original file in multiple viewers, not just one app
4. Check whether the source image relies on EXIF orientation metadata
5. If your pipeline strips EXIF before upload, make sure rotation is baked into the pixels
6. If you re-encode images upstream, confirm the orientation is preserved correctly
7. Keep one known-good test image from iPhone or HEIC capture for comparison

Start with a direct API test

The easiest way to isolate the issue is to remove your app and test the original file directly against the API:

curl -H 'x-api-key: YOUR_API_KEY' \
-f https://api.backgrounderase.com/v2 \
-F 'image_file=@/absolute/path/to/input.jpg' \
-F 'format=png' \
-o output.png

Or from JSON if that is how your system normally sends images:

{
  "image_base64": "BASE64_IMAGE_HERE",
  "format": "png"
}

If the saved output from this direct test is upright, your API path is probably fine.

Inspect the source file itself

A big part of solving rotation bugs is understanding whether the source file stores orientation in metadata or already has the rotation baked into the pixels. You can inspect that in Python:

from PIL import Image, ImageOps, ExifTags

img = Image.open("input.jpg")
print("Original size:", img.size)
print("Original EXIF orientation:", img.getexif().get(274))

fixed = ImageOps.exif_transpose(img)
print("Transposed size:", fixed.size)

fixed.save("normalized.jpg")

This helps answer the most important question: is the file truly upright, or does it only appear upright in viewers that honor EXIF orientation?

Compare the API output on disk

Save the API output locally and inspect it outside your app:

import requests

with open("input.jpg", "rb") as f:
    response = requests.post(
        "https://api.backgrounderase.com/v2",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"image_file": f},
        data={"format": "png"},
        timeout=120,
    )

response.raise_for_status()

with open("output.png", "wb") as out:
    out.write(response.content)

print("Saved output.png")

If the saved file looks correct in a standard image viewer but wrong in your product UI, the issue is almost always in the display layer or an additional transform applied after download.

Normalize orientation upstream if needed

In some pipelines, the cleanest solution is to normalize the file before it ever reaches the API. That is especially true when you have multiple image-processing steps, thumbnails, client previews, or uploads from environments that handle EXIF differently.

For Node.js pipelines, a common approach is to normalize with Sharp:

import sharp from "sharp";

await sharp("input.jpg")
  .rotate()
  .toFile("normalized.jpg");

That way, every downstream consumer in your system works with a file whose rotation is already baked into the pixels.

A note about HEIC and iPhone photos

The API also enables HEIC and HEIF support. That is useful because mobile images often rely on metadata-heavy workflows where orientation is a major source of confusion.

In practice, iPhone and HEIC-originated images are exactly the kinds of files where EXIF-aware normalization matters most. If you are seeing inconsistent rotation specifically with mobile uploads, compare the original file, the uploaded file, and the displayed result after any client-side conversions.

The most common root cause in apps

The most common real-world issue is not that the API rotates the image incorrectly. It is that one stage of the system uses EXIF-aware display and another stage does not. Once that happens, different parts of the product start disagreeing about what “upright” means.

That is why the cleanest engineering approach is often to normalize orientation once near ingest and then keep all later steps working from already-corrected pixels.

Final recommendation

If you are seeing rotation issues, start from the assumption that the API is already trying to correct EXIF orientation, because it is. The next step is to find where the mismatch is being introduced elsewhere in the stack.

• Test the original file directly against the API
• Inspect the source image’s EXIF orientation
• Save the API result and inspect it outside your app
• Check upstream compression or conversion steps
• Check downstream UI rendering or canvas export logic
• Normalize orientation once near ingest if needed

In most cases, that reveals the real issue quickly: not “the API rotated my image,” but “different parts of the pipeline treated EXIF orientation differently.”