Alt text generation

This endpoint lets you generate alt text for an image using AI, tailored to your preferred language, brand, and keywords.

The API takes a public image URL and returns a generated alt text along with metadata about the request. You can optionally guide the output by specifying a brand name or keywords to include.

Typical use cases include product feeds, blog platforms, content automation, and custom CMS integrations.

Request

Endpoint

POST https://app.alttextlab.com/api/v1/alt-text/generate

Request headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Before making a request, make sure you're authenticated using your API key. You can find detailed instructions in the Authentication section below.

Request body

Send a JSON object with the following structure:

imageUrl (string, required)

The public URL of the image to process.

lang (string, optional)

The language code for the generated alt text.
If not provided, the system will use the default language set in your account's general settings.
Example values: "en", "pl", "de".
You can find the full list of supported languages and their codes in the supported languages section.

style (string, optional)

Controls the tone and level of detail in the generated alt text.
If not provided, the system will use the default style set in your account's general settings.
Use one of the supported styles: `"descriptive"`, `"neutral"` (default), `"matter-of-fact"`, `"minimal"`
Learn more about writing styles

keywords (string[], optional)

A list of keywords to include or emphasize in the alt text.
This is useful for SEO or content alignment.
Example: "healthy breakfast", "avocado toast", "food blog"

ecommerce (object, optional)

Provide structured product information to generate alt text optimized for e-commerce use cases.
Including any of the fields below will automatically activate E-commerce Mode, which adjusts the output to better suit online stores, product listings and marketplaces.
Fields:
- product (string): Name or type of the product. Example: "sneakers", "office chair"
‍- brand (string): Brand of the product. Example: "Nike", "Herman Miller"
‍- color (string): Dominant color or palette. Example: "black", "ivory white"
‍- material (string): Material of the product. Example: "leather", "ceramic"

context (object, optional)

You can provide additional context to improve the accuracy and relevance of generated alt text. Images are not always clear or self-explanatory. In some cases, it may be difficult to understand what exactly is shown in the image without additional information.

The context field helps the AI better understand:

• what is actually shown in the image
• why it is used on the page
• how it relates to surrounding content

This leads to more accurate, meaningful, and SEO-friendly alt text.

‍

Fields:
- personName (string): If a person is clearly the main subject of the image (e.g. portrait, speaker, or main figure), the AI will use the provided name in the alt text. Example: "Elon Musk"

- pageTitle (string): The title of the page or article where the image is used. Helps clarify ambiguous images by providing high-level context. Example: "How to choose a CNC machine for woodworking"

- sectionHeading (string): The heading of the section where the image appears. Useful for understanding the local context within a page. Example: "Types of CNC machines"

- description (string): Additional description or explanation related to the image. Use this if you already have some structured or editorial context. Example: "Industrial woodworking machine used for precision cutting"

- surroundingText (string): Text surrounding the image (e.g. paragraph, caption, or nearby content). Example: "This type of CNC machine is commonly used for cutting wooden panels in furniture production."

Request examples

CURL

curl -X POST https://app.alttextlab.com/api/v1/alt-text/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"imageUrl": "https://example.com/image.jpg", "lang": "en"}'

Node.js

const fetch = require('node-fetch');

const response = await fetch('https://app.alttextlab.com/api/v1/alt-text/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    imageUrl: 'https://example.com/image.jpg'
    lang: 'en',
    keywords: ['eco-friendly', 'minimalist'],
    ecommerce: {
      product: "T-shirt Relaxed Fit",
      brand: "Acme Co."
    }
  })
});

const data = await response.json();

Response body

A successful response returns a JSON object with the following structure:

id (string)

A unique identifier for the alt text generation request.

imageUrl (string)

The original image URL that was submitted.

lang (string)

The language used for the generated alt text. Matches the lang field from the request.

count (number)

The number of characters in the generated alt text (result).

ecommerce (object)

Structured information provided to support e-commerce-specific generation.
- product (string): Name or type of the product.
- brand (string): Brand of the product.
- color (string): Color of the product.
- material (string): Material of the product.

style (string)

The writing style used for generating the alt text.

keywords (string[] | null)

The list of keywords used to guide the generation, or null if none were provided.

result (string | null)

The generated alt text. Will be null if the request failed or is still processing.

status (string)

The status of the generation request. Possible values include: "pending", "generated", "failed"

Rate Limits

To ensure platform stability and fair usage, API requests are subject to the following rate limits:

• Per second: up to 5 requests
• Per minute: up to 120 requests
• Per day: up to 100,000 requests

If you exceed any of these limits, the API will respond with a rate limit error. Limits are reset automatically after their respective time windows expire.

Tip: If you expect higher traffic or need custom limits, please contact our support team.

‍