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

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"

keywords (string[], optional)

A list of keywords to include or emphasize in the alt text.
This is useful for SEO or content alignment.
Example: ["eco-friendly", "minimalist"]

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"

‍