Images

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).
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

Request body

asyncboolean

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.

gpt_promptstring

[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}}"

keywordsstring[]

[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_sourcestring

[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.

langstring

The language(s) for the generated alt text. Use comma-separated language codes (e.g., "en,es,fr"). Use one of our <ins>supported language codes</ins> 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_charsinteger

[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 <a href="https://alttext.ai/docs/webui/account/#style-and-level-of-detail" target="_blank">our documentation</a> 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_keywordsstring[]

[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

overwriteboolean

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_secsinteger

[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_urlstring

[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

Successful alt text generation.

asset_idstring

The unique ID of the image.

urlstring

The URL of the image. Will be null if the image was added via raw file upload.

alt_textstring

The assigned alt text of the image.

alt_textsobject

Alt text in requested languages, with language codes as keys.

metadataobject

Any custom information you want to store. This will be passed back on all API requests and webhooks.

created_atinteger

Creation date of the image, in seconds since epoch.

errorsobject

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.

Changes

No recorded changes to this operation across all 1 revision of this API.