> ## Documentation Index
> Fetch the complete documentation index at: https://www.alttextlab.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Alt text generation

> Generate alt text for an image using the AltTextLab API.

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](/api/authentication) for details. Replace `YOUR_API_KEY` with your actual API key from [dashboard settings](https://app.alttextlab.com/settings/api-keys).

## Request

<CodeGroup>
  ```bash cURL theme={null}
  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."
      }
    }'
  ```

  ```javascript Node.js theme={null}
    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();
  ```

  ```php PHP theme={null}
  $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);
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<ParamField body="imageUrl" type="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.
</ParamField>

<ParamField body="lang" type="string">
  Language code for the generated alt text (e.g. `"en"`, `"pl"`, `"de"`). Defaults to the language set in your [account settings](https://app.alttextlab.com/settings/general). See [supported languages](/features/supported-languages).
</ParamField>

<ParamField body="style" type="string">
  Writing style: `"descriptive"`, `"neutral"` (default), `"matter-of-fact"`, or `"minimal"`. Defaults to account settings. See [writing styles](/features/writing-styles).
</ParamField>

<ParamField body="keywords" type="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.
</ParamField>

<ParamField body="ecommerce" type="object">
  Product metadata for e-commerce-optimized alt text. Including any field activates [E-commerce Mode](/features/ecommerce-mode).

  <Expandable title="properties">
    <ParamField body="product" type="string">
      Product name or type. Example: `"sneakers"`
    </ParamField>

    <ParamField body="brand" type="string">
      Brand name. Example: `"Nike"`
    </ParamField>

    <ParamField body="color" type="string">
      Dominant color or palette. Example: `"black"`
    </ParamField>

    <ParamField body="material" type="string">
      Product material. Example: `"leather"`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="context" type="object">
  Additional context to improve accuracy for ambiguous images. Context clarifies meaning — it does not override what is visible.

  <Expandable title="properties">
    <ParamField body="personName" type="string">
      Name of the main person depicted.
    </ParamField>

    <ParamField body="pageTitle" type="string">
      Title of the page where the image appears.
    </ParamField>

    <ParamField body="sectionHeading" type="string">
      Heading of the section containing the image.
    </ParamField>

    <ParamField body="description" type="string">
      Editorial description or explanation.
    </ParamField>

    <ParamField body="surroundingText" type="string">
      Text near the image — caption, paragraph, etc.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customFields" type="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"}`
</ParamField>

## Response body

<CodeGroup>
  ```json 200 OK theme={null}
  {
    "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"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key."
  }
  ```

  ```json 429 Too Many Requests theme={null}
  {
    "error": "Too Many Requests",
    "message": "Rate limit exceeded. Retry after 1 second."
  }
  ```
</CodeGroup>

<ResponseField name="id" type="string">
  Unique identifier for the generation request.
</ResponseField>

<ResponseField name="imageUrl" type="string">
  The original image URL submitted.
</ResponseField>

<ResponseField name="lang" type="string">
  Language used for generation.
</ResponseField>

<ResponseField name="result" type="string | null">
  The generated alt text. `null` if the request failed or is still processing.
</ResponseField>

<ResponseField name="status" type="string">
  `"generated"` or `"failed"`. Credits are deducted only when the status is `"generated"`. A `"failed"` response does not consume credits.
</ResponseField>

<ResponseField name="style" type="string">
  Writing style used.
</ResponseField>

<ResponseField name="keywords" type="string[] | null">
  Keywords used, or `null` if none were provided.
</ResponseField>

<ResponseField name="count" type="number">
  Character count of the generated alt text.
</ResponseField>

<ResponseField name="ecommerce" type="object">
  The e-commerce fields submitted with the request (`product`, `brand`, `color`, `material`).
</ResponseField>

<ResponseField name="customFields" type="object | null">
  The key-value pairs submitted with the request, returned unchanged. `null` if none were provided.
</ResponseField>