---
title: "Cancel an image"
method: POST
path: "/images/{id}/cancel"
tags: ["Images"]
---

# Cancel an image

`POST /images/{id}/cancel`

## Request

- Base URL: `https://www.iminify.com/api/v1`
- URL: `https://www.iminify.com/api/v1/images/{id}/cancel`
- Auth: HTTP bearer

Calls off an image still waiting in the queue. Once a worker has picked it up it runs to the end.

## Path parameters

- `id` string, uuid, required

## Response `200`

OK.

- object
  - `data` Image, required
    - `id` string, uuid, required: The image's id.
    - `status` 'queued' | 'optimizing' | 'completed' | 'failed' | 'already-optimized' | 'cancelled', required
    - `name` string, required: The name the optimized copy downloads under: the uploaded name, or the one you gave it, with the delivered format's extension. An `auto` conversion has no format until it finishes, so until then the extension is the uploaded file's own.
    - `original` object, required: The file as it was uploaded.
      - `name` string, required: The file name it downloads under.
      - `format` string, required: The file's format, as its extension: `jpg`, `png`, `webp`, `avif`, `gif`, `heic`, `tiff` and so on.
      - `size` integer, required: Its size in bytes.
      - `width` integer, required: Its width in pixels, the way it displays: a phone photo stored on its side is measured upright.
      - `height` integer, required: Its height in pixels, the way it displays.
      - `download_url` string, uri, required: Where to download it with your key.
    - `optimized` object, nullable, required: The optimized copy, or `null` until the image has finished.
      - `name` string, required: The file name it downloads under.
      - `format` string, required: The file's format, as its extension: `jpg`, `png`, `webp`, `avif`, `gif`, `heic`, `tiff` and so on.
      - `size` integer, required: Its size in bytes.
      - `width` integer, required: Its width in pixels, the way it displays: a phone photo stored on its side is measured upright.
      - `height` integer, required: Its height in pixels, the way it displays.
      - `download_url` string, uri, required: Where to download it with your key.
    - `saved_bytes` integer, nullable, required: Bytes the optimized copy saves against the original. Negative when a conversion or an enlargement made the file bigger. `null` until the image has finished.
    - `saved_percent` number, nullable, required: The same saving as a percentage of the original, to two decimal places. `null` until the image has finished.
    - `settings` object, required: The settings the image was compressed with, as they were sent.
      - `level` 'none' | 'lossless' | 'ultra' | 'smart', required
      - `format` 'auto' | 'webp' | 'avif' | 'png' | 'jpg', required
      - `keep_metadata` boolean, required: Whether the EXIF metadata was kept.
      - `width` integer, nullable, required: The width it was resized to, or `null`.
      - `height` integer, nullable, required: The height it was resized to, or `null`.
      - `scale` integer, nullable, required: The percentage it was scaled to, or `null`.
    - `alt_text` object, nullable, required: The AI alt text and suggested file name, or `null` when none was asked for. See [Alt text and file names](/docs/images#alt-text-and-file-names).
      - `status` 'pending' | 'written' | 'failed' | 'skipped', required: Where a result's AI alt text stands. `pending`: asked for and not written yet (only a finished result shows it as in progress; a failed compression keeps the request for its retry). `written`: the text and the suggested file name are stored. `failed`: the model refused, or the call or its thumbnail failed; it can be asked for again. `skipped`: asked for on a day whose alt texts were spent.
      - `text` string, nullable, required: One sentence for the image's `alt` attribute, or `null` until it is written.
      - `language` string, nullable, required: The language tag it was written in.
      - `suggested_name` string, nullable, required: A short descriptive file name without an extension, ready for the rename call, or `null` until it is written or when the model offered none.
    - `scan_id` string, uuid, nullable, required: The page scan that found the image, or `null` for an upload.
    - `source_url` string, uri, nullable, required: The address the image was fetched from: the image's address on the scanned page, or the `url` you sent instead of a file. `null` for a file you sent.
    - `share_url` string, uri, nullable, required: The public page while the image is shared, or `null`.
    - `created_at` string, date-time, required: When the image was queued.
    - `updated_at` string, date-time, required: When anything about it last changed, its status included.

## Other responses

- `401`: `unauthenticated`: No key was sent, or the key does not exist (it was mistyped or deleted). Send it as `Authorization: Bearer <key>`.
- `403`: `email_not_verified`: The key belongs to an account whose email address is not verified yet. Follow the link in the verification email, then call again with the same key. `account_banned`: The account behind the key has been banned. Its keys stop working with the ban.
- `404`: `not_found`: No image or scan with that id on your account, or no such address. An id from another account answers the same way as one that never existed.
- `409`: `image_not_cancellable`: Only an image still waiting in the queue can be cancelled. This one has started, or already ended.
- `429`: `rate_limited`: One of your per-minute limits is spent: requests, compressions or page scans. The compressions and scans are counted together with the website's, so work queued there counts too. Nothing was done; wait for the number of seconds in the `Retry-After` header and send it again.

---

[API](https://skmtc.dev/iminify/apis/iminify-api.md) · [All operations](https://skmtc.dev/iminify/apis/iminify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/iminify/apis/iminify-api/revisions/12dc614c2c21?raw)