--- title: "Write an image's alt text" method: POST path: "/images/{id}/alt-text" tags: ["Images"] --- # Write an image's alt text `POST /images/{id}/alt-text` ## Request - Base URL: `https://www.iminify.com/api/v1` - URL: `https://www.iminify.com/api/v1/images/{id}/alt-text` - Auth: HTTP bearer Asks AI for the alt text and suggested file name of a finished image: one sent with `alt_text` off, compressed before alt text existed, whose alt text failed, or skipped on a day that was used up. A written one can be asked again in another language. It counts one against your daily AI alt texts, unless an image with the same bytes already has one in that language, which is copied at once and costs nothing. The answer is the image; poll it until `alt_text.status` is no longer `pending`. While one is being written, asking again changes nothing. ## Path parameters - `id` string, uuid, required ## Request body - WriteAltTextRequest: The language to write the alt text in, and whether its suggested name renames the download. Both are optional. - `alt_text_language` 'en' | 'es' | 'fr' | 'de' | 'it' | 'pt' | 'nl' | 'pl' | 'sv' | 'tr' | 'ru' | 'uk' | 'ar' | 'fa' | 'he' | 'hi' | 'id' | 'vi' | 'th' | 'ja' | 'ko' | 'zh-Hans' | 'zh-Hant': The language to write the alt text in, as one of these tags: `en` (English), `es` (Spanish), `fr` (French), `de` (German), `it` (Italian), `pt` (Portuguese), `nl` (Dutch), `pl` (Polish), `sv` (Swedish), `tr` (Turkish), `ru` (Russian), `uk` (Ukrainian), `ar` (Arabic), `fa` (Persian), `he` (Hebrew), `hi` (Hindi), `id` (Indonesian), `vi` (Vietnamese), `th` (Thai), `ja` (Japanese), `ko` (Korean), `zh-Hans` (Simplified Chinese), `zh-Hant` (Traditional Chinese). The suggested file name follows it when the language is written in the Latin alphabet, and is in English otherwise. - `use_suggested_name` boolean: Rename the optimized copy to the suggested file name as soon as the alt text arrives, unless it already has a new name by then: yours, or an earlier suggestion. ## Response `202` Queued. `Location` points at the new record. - 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 `. - `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_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. `daily_limit_reached`: Your plan's images, page scans or AI alt texts for the day are used up. `Retry-After` holds the seconds until the rolling 24-hour window opens again. An image sent while only the alt texts are used up still compresses, without one. - `503`: `alt_text_not_available`: AI alt text is switched off on the service right now. Images still compress; ask for alt text again later. --- [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)