AI alt text generator for Python: installation and configuration

The dockaccess-alt-generator package connects a Python application to the DockAccess alt generator. It gives you a synchronous and an asynchronous client for any framework, a dockaccess-alt command for terminals and CI pipelines, and ready-made helpers for FastAPI, Django and Flask. It checks and rebuilds every image before sending it and returns plain-text descriptions. Your application decides where to save the alt and renders it in its templates.

Requirements

You need Python 3.10 or newer, a verified DockAccess account and a site with ALT Generator enabled; the free plan is enough to start. pip installs the two dependencies, httpx and Pillow. HEIC photos need the heif extra; AVIF needs a Pillow build with AVIF support.

Step 1. Install the package

pip install dockaccess-alt-generator
Copy text

The extras add what a helper needs if your project does not have it yet: pip install "dockaccess-alt-generator[fastapi]", [django], [flask] or [heif]. With uv or Poetry use uv add dockaccess-alt-generator or poetry add dockaccess-alt-generator. The package is imported as dockaccess_alt.

Step 2. Connect the application

1. In DockAccess, open My sites, add or select a site, check its production domain and enable ALT Generator. Copy the site token.
2. Run the following command in the project directory. Enter the site token, the public address of the application and the email and password of the DockAccess account. The password is used for connecting and is not stored.

dockaccess-alt connect
dockaccess-alt status
Copy text

The command writes DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN, DOCKACCESS_ALT_SECRET and DOCKACCESS_ALT_HOME_URL to .env, readable by its owner only. Load that file the way your project loads configuration (python-dotenv, pydantic-settings, docker --env-file) or pass env_file=".env" as in the examples below. With a secrets manager, --show prints the values instead of writing the file; keep that output out of public logs.

The application address must be one of the site’s domains. A local address such as http://localhost:8000 is accepted for development but does not confirm a production domain: connect again with the public address before going live. In CI, run dockaccess-alt connect --no-input --token … --login … --url https://example.com with the password in the DOCKACCESS_PASSWORD variable. Use --overwrite only when intentionally replacing an existing installation; it rotates the connection secret. The connected application appears among the site’s integrations in DockAccess as Python.

Step 3. Generate one description

from dockaccess_alt import AltGenerator

generator = AltGenerator.from_env(env_file=".env")

with open("media/products/backpack.jpg", "rb") as photo:
    result = generator.generate(
        photo,
        language="en",
        tone="neutral",
        context="Product page: city backpack, front view",
    )

alt = result.text
image_uuid = result.image_uuid
# Save the text, its language and image_uuid with the correct image in your database.
Copy text

Create one generator per process and reuse it; it is thread-safe. generate() accepts bytes, an open binary file, a Pillow image or an upload from FastAPI, Django or Flask. A path is never read implicitly: use ImageSource.from_path(path, within=MEDIA_ROOT), which refuses files outside the named directory, including those reached through symbolic links. language accepts language codes and locales such as pl_PL, context up to 500 characters and variants 1–3 alternatives. The returned text is plain text; let your template escape it in the alt attribute.

Step 4. Use it in your framework

FastAPI (and other asyncio frameworks): open one asynchronous generator for the application and receive it as a dependency.

from contextlib import asynccontextmanager

from fastapi import FastAPI, UploadFile
from dockaccess_alt import AltGeneratorError
from dockaccess_alt.fastapi import AltGeneratorDep, alt_generator_exception_handler, alt_generator_lifespan


@asynccontextmanager
async def lifespan(app: FastAPI):
    async with alt_generator_lifespan(app):
        yield


app = FastAPI(lifespan=lifespan)
app.add_exception_handler(AltGeneratorError, alt_generator_exception_handler)


@app.post("/products/{product_id}/photo")
async def upload_photo(product_id: int, photo: UploadFile, generator: AltGeneratorDep):
    result = await generator.generate(photo, language="en")
    return {"alt": result.text}
Copy text

The exception handler answers a rejected image with 422, an exhausted allowance with 429 and an unavailable generator with 503, without revealing account details. Images are processed in a worker thread, so the event loop is not blocked.

Django: add "dockaccess_alt.django" to INSTALLED_APPS for translated validation messages. The language follows LANGUAGE_CODE; optional settings go in DOCKACCESS_ALT, for example {"CONTEXT": "Furniture shop"}.

from dockaccess_alt.django import get_alt_generator
from dockaccess_alt.django.validators import validate_image


class Product(models.Model):
    photo = models.ImageField(upload_to="products/", validators=[validate_image])
    photo_alt = models.CharField(max_length=500, blank=True)


result = get_alt_generator().generate(product.photo, context=product.name)
product.photo_alt = result.text
product.save(update_fields=["photo_alt"])
Copy text

Flask: DockAccessAlt(app) reads DOCKACCESS_ALT_* from app.config or the environment, and get_alt_generator().generate(request.files["photo"]) generates in a view. register_error_handler(app) adds the same JSON error answers as in FastAPI.

Step 5. Generate in the background and in batches

For many images, generate in a task rather than in the request. Pass the record’s identifier to the task, not the generator: the keys cannot be serialized on purpose.

from celery import shared_task
from dockaccess_alt import RateLimitedError, ServerError, TransportError
from dockaccess_alt.django import get_alt_generator


@shared_task(bind=True, max_retries=5)
def generate_alt(self, product_id):
    product = Product.objects.get(pk=product_id)
    try:
        result = get_alt_generator().generate(product.photo, context=product.name)
    except RateLimitedError as error:
        raise self.retry(countdown=error.retry_after)
    except (ServerError, TransportError) as error:
        raise self.retry(countdown=60) from error
    Product.objects.filter(pk=product_id).update(photo_alt=result.text)
Copy text

generator.generate_many(items) processes images in sequence, waits after a temporary rate limit, skips rejected files and stops when the allowance is exhausted or the site is switched off. Each result carries the key you passed with the image, such as a record ID.

Generate in a pipeline

The dockaccess-alt generate command processes files and directories, for example the images of a static site in GitLab CI or GitHub Actions:

dockaccess-alt generate static/img -r --lang en --manifest alts.json --format jsonl
Copy text

The alts.json manifest keeps the descriptions per image and language together with the file’s SHA-256, so the next run generates only new and changed images. Keep it in the repository or a CI cache and read it in your site generator. --max 200 limits generations in one run; --dry-run and dockaccess-alt check verify images without sending them. Store DOCKACCESS_ALT_KEY, DOCKACCESS_ALT_SITE_TOKEN and DOCKACCESS_ALT_SECRET as masked CI variables.

• Exit code 0: done; 1: some images were rejected and the rest generated.
• 2: configuration error, for example no key or a missing file.
• 3: the application is not connected or the generator is disabled or paused for the site.
• 4: the allowance is exhausted; run again after it renews.
• 5: DockAccess could not be reached.

Images and data protection

The package recognizes the format by content, not by the file name, and refuses SVG, damaged files and images with excessive dimensions before decoding them. Accepted formats are JPEG, PNG, GIF, WebP, AVIF and HEIC. Each image is turned upright, scaled down to 2048 pixels on its longest side and rebuilt from pixels as JPEG or WebP, so GPS location, camera data, author, ICC profile and comments stay on your server. generator.prepare(image) runs these checks without sending anything, for example when validating an upload.

Allowances, verification and errors

generator.usage() returns used, limit, remaining, is_monthly and resets_at. Before generating, the package asks DockAccess whether the generator is still active for the site and remembers the answer for 300 seconds. A disconnected, disabled or paused service raises GeneratorUnavailableError. If DockAccess is temporarily unreachable, generation continues and the generator still enforces the account limits.

• InvalidImageError: the file was rejected locally and nothing was sent; reason says why.
• AuthenticationError: the key was not accepted; run dockaccess-alt connect again.
• LimitReachedError: the allowance is exhausted; period tells a daily from a monthly window.
• RateLimitedError: wait retry_after seconds and retry.
• ServerError and TransportError: temporary problems; retry later.

The standard free allowance is 10 image generations per UTC day and 1 site with ALT Generator enabled. Ready-made CMS integrations are available on the free plan.

Paid ALT generator plans use a calendar-month allowance, available in full without a daily split. The site allowance is separate from the generation allowance. Your current allowance and usage are shown in the account dashboard. Check current plans

The generation allowance is shared across the account: the online tool, connected sites and API use the same pool. Generating again also uses the allowance; editing a saved text by hand does not generate a new description.

Daily usage resets at 00:00 UTC; monthly usage resets at 00:00 UTC on the first day of the next calendar month. This is independent of the subscription payment date. In Poland, 00:00 UTC is 01:00 in winter and 02:00 in summer. The usage service returns the exact renewal time as resets_at.

Bulk generation processes images in sequence. When the account allowance is exhausted, completed descriptions stay saved and the batch stops. Continue with the remaining images after renewal or a plan upgrade. A temporary request-rate limit causes a wait and retry instead. Older plugin versions may label a monthly counter “daily”; use the period and renewal time shown in your DockAccess account.

Testing and synchronization

In your tests, FakeAltApi("Green backpack with two front pockets") from dockaccess_alt.testing answers like DockAccess without the network, a key or using the allowance; images are still checked as in production. Its generator() or async_generator() replaces the real generator, and assert_generated(1) checks the number of generations.

To send a description corrected in your application back to the account, call generator.update_alts(image_uuid, [(alt, "en")]). The package also includes signed receivers for descriptions edited in the account (FastAPI, Django, Flask), but account editing currently does not send changes to applications; save corrections in your application as well. See the REST API guide for the protocol.

Disconnect with dockaccess-alt disconnect, which also removes the keys from .env. Restart long-running processes after rotating connection values. Before production, generate one image and review the description using the general guide.