Skip to content

InstantAlt: Universal HTML / JS Snippet

Using our InstantAlt feature, you copy + paste a small piece of HTML code into your web pages, and we'll automatically generate and serve alt text for your images. That's all you need to do—no complex integrations, no API calls… just add the code snippet and you're done!

Requirements

To use the InstantAlt feature, you'll need to be on an active recurring subscription plan. This is because we not only generate the alt text for any images on your pages, but we also continuously serve that alt text in real-time into your web page HTML. So your account will need to be active in order for us to support real-time serving of alt text to your website.

Creating a Site

You'll need to let us know the domain name of your website that will be needing alt text. We'll create a custom HTML code snippet that you copy + paste into your pages.

  1. Go to the Account: InstantAlt Sites page in your AltText.ai account.
  2. Click the button to create a new Site.

  3. Enter your website's domain name exactly as visitors see it in their browser:

    Important: Match your actual website URL format: - If your site uses www.yoursite.com, enter: www.yoursite.com - If your site uses just yoursite.com (no www), enter: yoursite.com - If you use both formats, create one site entry and it will work for both - For subdomains like shop.yoursite.com, enter the specific subdomain: shop.yoursite.com - To cover all subdomains at once, use a wildcard: *.yoursite.com

    Examples: - www.mystore.com (most common) - mystore.com (without www) - shop.mystore.com (specific subdomain) - *.mystore.com (covers all subdomains)

  4. Click the Create button, and you will see your site in the list of all sites for your account.

Adding the HTML Snippet

When you add the HTML snippet to your web pages, you will start to get alt text added to any image which is currently missing alt text.

  1. From your list of sites, you will see the HTML Code that is needed. Click the Copy button to copy the code to your clipboard.
  2. In your web page code on your site, paste the HTML snippet anywhere in the <head> section of your site. The snippet needs to be on all pages where you want alt text added to images. If you're unsure how to do this, ask your web developer for help.
  3. That's it — you will start to get alt text added to your images on your site!

Setting Alt Text Language

InstantAlt will use the default language set in your Account Settings. However, you can override this on any page by directly specifying the language code to use as a lang= query-string parameter on the InstantAlt snippet URL.

Example:

  • Your original InstantAlt snippet URL (uses language from account settings):
    • https://ujs.alttext.ai/alttextai-ujs.js?site-key=abc123
  • Modified URL to always use German, regardless of account settings:
    • https://ujs.alttext.ai/alttextai-ujs.js?site-key=abc123&lang=de

Advanced Configuration

The InstantAlt script supports setting config parameters via a window object as well. Just define window.ataiConfig before your InstantAlt embed script on your pages:

<script>
  window.ataiConfig = {
    // Your custom settings go here
    siteKey: "123456789",
    lang: "de",
    keywords: "Hawaii beach vacations, surfing adventures",
    overwrite: true, // Replace existing alt text
    excludedElements: [
      ".google-map",
      ".decorative-image"
    ]
  };
</script>

<script type="module" defer id="alttextai-ujs" src="https://ujs.alttext.ai/alttextai-ujs.js?site-key=abc123"></script>

The following config parameters are recognized on the window.ataiConfig object:

siteKey

string— Optional override (the key is already embedded in the script URL). Use this only when you need to inject a dynamic key from server-side code or a CMS.

lang

string — ISO-639-1 language code ("fr", "es", …). Sets the language for alt-text generation and caching. See Supported Languages for the current list.

keywords

string — Comma-separated list of SEO keywords to use in the generated alt text.

keywordSource

string — Text to use as the source of keywords for the alt text. This field will only be used if the keywords field is blank.

ecommProduct

string — The name of the product in the image.

ecommBrand

string — [optional] The brand name of the product in the image.

overwrite

boolean — When set to true, replaces existing alt text on images. By default (false), InstantAlt only adds alt text to images that don't already have it. Enable this if you want to update outdated or incorrect alt text across your site.

excludedElements

string[] — Array of CSS selectors. Any image inside an element that matches one of these selectors is ignored. This leverages document.querySelectorAll under the hood, so you can pass any valid selector.

How It Works

Once you add the HTML Snippet to your site, any time a browser (or Google) loads your web page, a request will be made in the background to get alt text from our servers.

Site Status: Pending vs Active

When you first create a site, it will show as "Pending" status in your Sites dashboard. This is normal behavior and indicates that we haven't processed any images from your site yet.

A site remains "Pending" until: - An image without alt text is loaded on a page with the InstantAlt script - We successfully process that first image

Common scenarios where sites stay "Pending": - The script is installed but no pages with images have been visited yet - All images on visited pages already have alt text (so no processing occurs) - The script is installed incorrectly or not loading properly

Once the first image is processed successfully, your site status will change from "Pending" to show the actual number of images processed.

First Request

The very first time a request is made to your site, we will start to generate alt text for your images. This first request will not result in alt text being added, since it takes a few seconds per image to generate alt text and we don't want your site to hang while that is happening.

Subsequent Requests

Once alt text has been generated for your images, any requests to your pages after that will immediately result in the generated alt text being added to your images.

Note

If you are testing the snippet on your site, remember the first request you make will not add alt text. Try making your second request after 20-30 seconds, in order to allow enough time for alt text generation to happen.

Testing Your Installation

To verify your InstantAlt script is working: 1. Visit a page on your site that has images WITHOUT alt text 2. Wait 20-30 seconds for processing 3. Refresh the page - you should see alt text has been added 4. Check your Sites dashboard - status should change from "Pending" to show processed count

Account Changes

If your account status changes, alt text served from our HTML Snippet may be affected. Here are some common account changes and how they affect alt text served to your sites through our code snippet:

  • Account No Longer on a Paid Subscription Plan
    • Alt text will no longer be added to images on any sites using the HTML snippet.
    • No new Sites can be created until the account is back on a paid plan.
  • Account Deleted
    • Alt text will no longer be added to images on any sites using the HTML snippet.
    • Ideally the customer (you) should remove the HTML snippet from your site.
  • Account Has No More Credits
    • Existing alt text that has already been generated will continue to be served.
    • No new alt text will be generated for images on the website.
    • Once more credits are added, it may take up to 1 hour for new alt text to be generated and served.