--- title: "POST /images" method: POST path: "/images" tags: ["Images"] --- # POST /images `POST /images` ## Request - Base URL: `https://alttext.ai/api/v1` - URL: `https://alttext.ai/api/v1/images` - Auth: API key in header `X-API-Key` Add an image and generate alt text. There are two ways to add an image: - Adding an image **by URL**: - The URL to your image must be publicly accessible. - Include the `url` field in your image JSON data. *DO NOT* include the `raw` field. - Adding an image by **sending a base64-encoded binary file**: - Use this method when your image is not accessible via URL (e.g. a local file). - Include the `raw` field in your image JSON data. *DO NOT* include the `url` field. - The `async` parameter is *not* supported for binary file uploads. All raw file uploads are processed synchronously. **Rate Limited**: Requests are limited to 4 calls per second. **Duplicate images**: If you try to add a URL which already exists in your library, the existing image data will be returned with a success response. You will *not* be charged any credits in this case. No webhook event will be sent, even if you requested `async`. **Note**: Image files are *never* stored permanently by AltText.ai. We simply store the URL you send for the image, and use that to temporarily fetch the image for analysis. After fetching the image, it is deleted and never persisted on our servers. If you upload an image file instead of a URL, the image is deleted immediately after being analyzed. #### Image requirements - Supported formats: JPEG, PNG, GIF, WEBP, BMP - Maximum file size: 16 MB - Minimum dimensions: 50 x 50 (smaller images may not be able to generate alt text). ## Request body - object - `image` ImageCreate - `url` string: The URL of the image that needs alt text. Either `url` or `raw` is *required* to be sent. - `raw` string: The base64-encoded image data, used when sending a local file that is not reachable via public URL. Encoding should conform to RFC 4648, with no line feeds. Either `url` or `raw` is *required* to be sent. - `asset_id` string: optional: Your own unique asset ID to use for this image. If not specified, a unique value will be automatically created. Cannot contain any of these characters: `?&#\/%<>+` - `tags` unknown[]: optional: Words or phrases associated with the image. - unknown - `metadata` object: optional: Any custom information you want to store. This will be passed back on all API requests and webhooks. - `async` boolean: Whether to add the image in the background or immediately (synchronously). When `async` is true, the API response will always be successful with an empty response body. Use webhooks to be notified when the image is added. - `ecomm` object: [optional] The ecommerce data to use when generating alt text specific to an ecommerce product. Providing the product and optional brand or color name will use our ecomm-specific vision system, which will include your product details in the generated alt text. - `product` string, required: The name of the product in the image. - `brand` string: [optional] The brand name of the product in the image. - `color` string: [optional] The specific color of the product in the image. - `gpt_prompt` string: [optional] A Final Pass prompt to run on the initially generated alt text. Be sure to include the `{{AltText}}` macro enclosed in two curly braces -- we will substitute this macro with the initially generated alt text, then run your prompt. The result will be returned as the alt text for the image. Prompts must be written in English, even if alt text is being generated in another language. Example prompt: *"Rewrite the following text in the style of William Shakespeare: {{AltText}}"* - `keywords` string[]: [optional] Array of keywords / phrases to be considered when generating the alt text. Typically only one or two of the keywords from the array will be used in the alt text, but all may be examined when generating the result. Useful for SEO optimized alt text. **Keywords must be in English**, even if requesting alt text in another language - `keyword_source` string: [optional] Text to use as the source of keywords for the alt text. This field will *only* be used if the `keywords` argument is blank. This text might be a product description, or a paragraph that describes the context of the images, etc. - `lang` string: The language(s) for the generated alt text. Use comma-separated language codes (e.g., `"en,es,fr"`). Use one of our [supported language codes](https://alttext.ai/support#faq-tech) for this parameter. You can request multiple languages by providing a comma-separated string (e.g. `"en,fr,es"`). **Multi-language behavior:** When requesting multiple languages for an existing image with `overwrite: false` (default when left blank), only missing languages will be generated. Existing alt text in previously generated languages will be preserved. If this parameter is not included, the default language for the account will be used. - `max_chars` integer: [optional] Maximum length of the generated alt text. If not specified, your account default value will be used. - `model_name` 'describe-detailed' | 'describe-regular' | 'describe-factual' | 'succinct-describe-factual' | 'describe-terse': [optional] The language model to use for alt text generation. See our documentation for details on each of these models. The model name strings correspond to the models below: * `describe-detailed` => Elaborated model * `describe-regular` => Standard model * `describe-factual` => Matter-of-fact model * `succinct-describe-factual` => Concise model * `describe-terse` => Terse model (usually less than 120 characters) - `negative_keywords` string[]: [optional] Array of negative keywords / phrases to be removed from any generated alt text. **Negative keywords must be in English**, even if requesting alt text in another language - `overwrite` boolean: If `true`, any existing image with the same URL or asset ID (if provided) will be overwritten with new result data. This parameter will force a regeneration of the alt text for an existing image. - `timeout_secs` integer: [optional] The maximum timeout, in seconds, to wait for alt text to be generated. It is *strongly recommended* to leave this at the default value unless you are prepared to deal with results that may not have alt text, or take longer than usual to be returned. - `webhook_url` string: [optional] Alternative webhook URL for notifications for this operation. * If this parameter is not set or has a value of `null`, then the default notification URL for the account will be used. * When this parameter is set, webhooks will be sent here *instead* of the default notification URL on the account. * If your account has a default notification URL set, but you do not want any webhooks sent for this operation, you can pass an empty string `""` as the value of this parameter. ## Response `200` Successful alt text generation. - Image - `asset_id` string: The unique ID of the image. - `url` string: The URL of the image. Will be `null` if the image was added via raw file upload. - `alt_text` string: The assigned alt text of the image. - `alt_texts` object: Alt text in requested languages, with language codes as keys. - `tags` unknown[]: Words or phrases that you want to associate with the image. - unknown - `metadata` object: Any custom information you want to store. This will be passed back on all API requests and webhooks. - `created_at` integer: Creation date of the image, in seconds since epoch. - `errors` object: Any errors associated with this image. Note - This will be an empty object for valid images. - `error_code` 'insufficient_credits' | 'invalid_params' | 'general': An identifier describing the type of error, if any. ## Other responses - `429`: Too many requests. Rate limit exceeded. - `4XX`: Invalid request. See image errors field for details. --- [API](https://skmtc.dev/alttext/apis/alttext-ai-api.md) · [All operations](https://skmtc.dev/alttext/apis/alttext-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/alttext/apis/alttext-ai-api/revisions/6eb62e8e450c?raw)