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

# Batch Generate Alt Text

> Generate alt text for multiple images in a single request

## Overview

Process multiple images efficiently in a single API call. This is ideal for bulk processing or when you need to generate alt text for multiple images at once.

<Endpoint method="post" url="https://api.gistmag.co.uk/batch" />

## Request Body

<ParamField body="api_key" type="string" required>
  Your GistMag API key
</ParamField>

<ParamField body="images" type="array<object>" required>
  Array of image objects to process. Each object must contain at least `image_url`.
</ParamField>

<ParamField body="images.image_url" type="string" required>
  The URL of the image
</ParamField>

<ParamField body="images.mode" type="string" default="short">
  The length of alt text for this specific image. Options: `short`, `long`, `seo`
</ParamField>

<ParamField body="images.language" type="string" optional>
  Language code for this specific image (default: en)
</ParamField>

<ParamField body="images.source" type="string" optional>
  Source identifier for tracking (web, api, extension, wordpress, shopify, batch)
</ParamField>

## Example Request

```bash theme={null}
curl -X POST https://api.gistmag.co.uk/batch \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    "images": [
      {
        "image_url": "https://example.com/image1.jpg",
        "mode": "short"
      },
      {
        "image_url": "https://example.com/image2.jpg",
        "mode": "long"
      },
      {
        "image_url": "https://example.com/image3.jpg",
        "mode": "seo"
      }
    ]
  }'
```

## Response

<ResponseField name="results" type="array">
  Array of alt text responses for each image
</ResponseField>

<ResponseField name="results[].alt_text" type="string">
  The generated alt text based on the selected mode
</ResponseField>

<ResponseField name="results[].short_alt_text" type="string" optional>
  Short version of alt text (if mode was short or all modes requested)
</ResponseField>

<ResponseField name="results[].long_alt_text" type="string" optional>
  Long version of alt text (if mode was long or all modes requested)
</ResponseField>

<ResponseField name="results[].seo_alt_text" type="string" optional>
  SEO-optimized version of alt text (if mode was seo or all modes requested)
</ResponseField>

<ResponseField name="results[].image_url" type="string">
  The original image URL
</ResponseField>

<ResponseField name="results[].generated_at" type="string">
  ISO timestamp of when the alt text was generated
</ResponseField>

<ResponseField name="total" type="number">
  Total number of images processed
</ResponseField>

<ResponseField name="successful" type="number">
  Number of successfully processed images
</ResponseField>

<ResponseField name="failed" type="number">
  Number of images that failed to process
</ResponseField>

### Example Response

```json theme={null}
{
  "results": [
    {
      "alt_text": "A beautiful sunset over the ocean",
      "short_alt_text": "Sunset over ocean",
      "long_alt_text": "A beautiful sunset over the ocean with orange and pink hues reflecting on the water",
      "seo_alt_text": "Sunset over ocean - beach photography - nature scene",
      "image_url": "https://example.com/image1.jpg",
      "generated_at": "2024-01-15T10:30:00Z"
    },
    {
      "alt_text": "A detailed description of a mountain landscape with snow-capped peaks and a clear blue sky",
      "image_url": "https://example.com/image2.jpg",
      "generated_at": "2024-01-15T10:30:05Z"
    },
    {
      "alt_text": "A city street at night with neon lights",
      "image_url": "https://example.com/image3.jpg",
      "generated_at": "2024-01-15T10:30:10Z"
    }
  ],
  "total": 3,
  "successful": 3,
  "failed": 0
}
```

## Rate Limits

Batch requests count as multiple individual requests for rate limiting purposes. Each image in the batch consumes one credit and counts toward your rate limit.

<Info>
  Batch processing is more efficient than making multiple individual requests, but still counts toward your usage limits.
</Info>