Alt text generation

This endpoint lets you generate alt text for an image using AI, tailored to your preferred language, writing style, keywords, product attributes, and contextual information. The API takes a public image URL and returns generated alt text along with metadata about the request.

Endpoint

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

Request headers

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

See Authentication for details. Replace YOUR_API_KEY with your actual API key from dashboard settings.

Request

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",
    "style": "neutral",
    "keywords": ["eco-friendly", "minimalist"],
    "ecommerce": {
      "product": "T-shirt Relaxed Fit",
      "brand": "Acme Co."
    }
  }'

  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',
  style: 'neutral',
  keywords: ['eco-friendly', 'minimalist'],
  ecommerce: {
  product: 'T-shirt Relaxed Fit',
  brand: 'Acme Co.'
}
})
});

  const data = await response.json();

$payload = json_encode([
    'imageUrl' => 'https://example.com/image.jpg',
    'lang'     => 'en',
    'style'    => 'neutral',
    'keywords' => ['eco-friendly', 'minimalist'],
    'ecommerce' => [
        'product' => 'T-shirt Relaxed Fit',
        'brand'   => 'Acme Co.',
    ],
]);

$ch = curl_init('https://app.alttextlab.com/api/v1/alt-text/generate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'x-api-key: YOUR_API_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

import requests

response = requests.post(
    'https://app.alttextlab.com/api/v1/alt-text/generate',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY',
    },
    json={
        'imageUrl': 'https://example.com/image.jpg',
        'lang': 'en',
        'style': 'neutral',
        'keywords': ['eco-friendly', 'minimalist'],
        'ecommerce': {
            'product': 'T-shirt Relaxed Fit',
            'brand': 'Acme Co.',
        },
    }
)

data = response.json()

string

required

Public URL of the image to process. The URL must be directly accessible without authentication or redirects — images behind login pages or private networks cannot be processed.

string

Language code for the generated alt text (e.g. "en", "pl", "de"). Defaults to the language set in your account settings. See supported languages.

string

Writing style: "descriptive", "neutral" (default), "matter-of-fact", or "minimal". Defaults to account settings. See writing styles.

string[]

Keywords to include or emphasize in the output. Useful for SEO alignment. Example: ["healthy breakfast", "avocado toast"].Keywords are not guaranteed to appear in the output. The model will include them when they fit naturally and are consistent with what is depicted. If a keyword cannot be added concisely or contradicts the image content, it will be omitted.

object

Product metadata for e-commerce-optimized alt text. Including any field activates E-commerce Mode.

Show properties

string

Product name or type. Example: "sneakers"

string

Brand name. Example: "Nike"

string

Dominant color or palette. Example: "black"

string

Product material. Example: "leather"

object

Additional context to improve accuracy for ambiguous images. Context clarifies meaning — it does not override what is visible.

Show properties

string

Name of the main person depicted.

string

Title of the page where the image appears.

string

Heading of the section containing the image.

string

Editorial description or explanation.

string

Text near the image — caption, paragraph, etc.

object

Arbitrary key-value pairs (string: string) returned in the response unchanged. Use them to attach identifiers or metadata for matching results to assets in your system. They have no effect on generation.

Maximum 30 keys per request
Maximum key length: 70 characters
Maximum value length: 250 characters

Example: {"sku": "TSHIRT-001", "catalogId": "summer-2025"}

Response body

{
  "id": "gen_abc123xyz",
  "imageUrl": "https://example.com/image.jpg",
  "lang": "en",
  "result": "A white ceramic mug with a minimalist design on a wooden table.",
  "status": "generated",
  "style": "neutral",
  "keywords": ["eco-friendly", "minimalist"],
  "count": 64,
  "ecommerce": {
    "product": "T-shirt Relaxed Fit",
    "brand": "Acme Co.",
    "color": null,
    "material": null
  },
  "customFields": {
    "sku": "TSHIRT-001",
    "catalogId": "summer-2025"
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key."
}

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 1 second."
}

string

Unique identifier for the generation request.

string

The original image URL submitted.

string

Language used for generation.

string | null

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

string

"generated" or "failed". Credits are deducted only when the status is "generated". A "failed" response does not consume credits.

string

Writing style used.

string[] | null

Keywords used, or null if none were provided.

number

Character count of the generated alt text.

object

The e-commerce fields submitted with the request (product, brand, color, material).

object | null

The key-value pairs submitted with the request, returned unchanged. null if none were provided.

Get started

Integrations

Web snippet

Developer API

Features

Guides

Endpoint

Request headers

Request

Response body

​Endpoint

​Request headers

​Request

​Response body

Endpoint

Request headers

Request

Response body