---
title: "Rename several images"
method: POST
path: "/images/rename"
tags: ["Images"]
---

# Rename several images

`POST /images/rename`

## Request

- Base URL: `https://www.iminify.com/api/v1`
- URL: `https://www.iminify.com/api/v1/images/rename`
- Auth: HTTP bearer

Gives every finished image in `ids` the same name followed by its place in upload order, oldest first: `trip-01`, `trip-02`. The number has at least two digits, more when the count needs them. A single image gets the name alone. Images that haven't finished are passed over, and if none has, the call is refused. It is all or nothing: when one of the names would be too long, none changes. Every id has to be one of your images; the ones that aren't are named in `errors`.

## Request body

- RenameImagesRequest: The images, by id, and the one name they are numbered under.
  - `ids` string[], required: The images, by id. 1 to 150.
  - `name` string, required: The name they share, without an extension.

## 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.
- `409`: `image_not_finished`: The call needs an optimized copy (to download, rename or zip it, or to write its alt text) and the image has not finished. In a batch call, none of the images named had finished.
- `422`: `validation_failed`: A field is missing or wrong, or the file or address did not pass the checks every upload goes through. `errors` names each field with its messages.
- `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)