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

# Share an image

`POST /images/{id}/share`

## Request

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

Gives a finished image a public page at an address nobody can guess, returned as `share_url`. Anyone with the link can see the optimized copy, compare it with the original, download either one, and run the original through Iminify with their own settings. The page is kept out of search engines. Sharing an image that is already shared keeps its link.

## 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_shareable`: Only a finished image whose files a browser can show can be shared. A HEIC or TIFF handed back unconverted cannot.
- `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)