.. include:: /Includes.rst.txt

.. _configuration:

=============
Configuration
=============

Extension Configuration
=======================

Configure the extension in **Admin Tools > Settings > Extension Configuration > nnaitools**.

API Key
-------

:Type: string
:Default: (empty)

Your OpenAI API key for accessing the ChatGPT API.

How to obtain an API key
~~~~~~~~~~~~~~~~~~~~~~~~

1. Go to `OpenAI Platform <https://platform.openai.com/>`__
2. Create an account or sign in
3. Navigate to **API Keys** in your account settings (https://platform.openai.com/api-keys)
4. Click **"Create new secret key"**
5. Copy the key immediately (it won't be shown again)
6. Paste the key into the extension configuration

.. important::

   Keep your API key secure. Never commit it to version control or share it publicly.

.. note::

   OpenAI API usage is billed separately from ChatGPT subscriptions. You'll need to add
   a payment method and purchase credits at https://platform.openai.com/account/billing

API URL
-------

:Type: string
:Default: ``https://api.openai.com/v1/chat/completions``

The OpenAI API endpoint URL. Usually you don't need to change this unless you're using
a proxy or alternative API provider.

Model
-----

:Type: string
:Default: ``gpt-4o-mini``

The OpenAI model to use for image analysis. Recommended models:

- ``gpt-4o-mini`` - Fast and cost-effective, good for most use cases
- ``gpt-4o`` - More capable but slower and more expensive

Exclude Path Patterns
---------------------

:Type: text (multiline)
:Default: (empty)

Regex patterns to exclude certain image paths from processing. Enter one pattern per line.

Example:

.. code-block:: text

   /fileadmin/templates/.*
   /fileadmin/_processed_/.*
   .*placeholder.*

Auto-generate on Save
---------------------

:Type: boolean
:Default: ``false``

When enabled, the extension will automatically generate ALT and title texts when a
``sys_file_reference`` record is saved and the texts are missing.

Image Detail Level
------------------

:Type: options (low, high, auto)
:Default: ``low``

Controls the image resolution sent to OpenAI for analysis:

- ``low`` - Images are resized to 512px (cheapest option, fastest)
- ``high`` - Images can be up to 2048px (more detail, higher cost)
- ``auto`` - Let OpenAI decide the appropriate resolution

.. tip::

   For most accessibility use cases, ``low`` is sufficient and significantly reduces costs.

Prompt Template
---------------

:Type: text
:Default: ``Analyze this image and create a very short ALT text (max. 50 characters) and a title text (max. 100 characters) for accessibility. {LANGUAGES} Reply only with valid JSON.``

The prompt sent to the AI for generating texts. Use ``{LANGUAGES}`` as a placeholder
for the language-specific instructions that will be automatically inserted based on
your site configuration.

Cost Control Settings
=====================

The extension provides built-in cost tracking and limiting to help you manage API expenses.

Cost per Input Tokens
---------------------

:Type: string
:Default: ``0.00015``

The cost in USD per 1000 input/prompt tokens. This is used to calculate estimated costs.

Default value corresponds to ``gpt-4o-mini`` pricing.

Cost per Output Tokens
----------------------

:Type: string
:Default: ``0.0006``

The cost in USD per 1000 output/completion tokens.

Default value corresponds to ``gpt-4o-mini`` pricing.

Max Cost Limit
--------------

:Type: string
:Default: (empty)

Maximum allowed cost in USD before blocking API requests. Leave empty for no limit.

When a limit is set:

- API requests will be blocked once the limit is reached
- A warning icon appears in the backend module toolbar
- Bulk processing will automatically stop
- The limit resets when you reset the token statistics

Example: Set to ``5.00`` to limit spending to $5 USD.

Site Language Configuration
===========================

You can disable AI text generation for specific languages in your site configuration.

1. Go to **Site Management > Sites**
2. Edit your site configuration
3. For each language, you'll find a checkbox **"Disable the automatic alt-/title-text generation via AI"**
4. Check this box to exclude the language from AI text generation

When a language is disabled:

- It will appear grayed out in the backend module's language dropdown
- No texts will be generated for this language during bulk processing
- The language will be skipped in auto-generation

Backend User Permissions
========================

To allow backend users access to the AI Tools module:

1. Go to **System > Backend Users**
2. Edit the user or user group
3. Under **Access Lists > Modules**, enable **File > AI Tools**

Support This Project
====================

If this extension saves you time and helps improve your website's accessibility,
please consider supporting its development:

.. tip::

   `Donate via PayPal <https://www.paypal.com/paypalme/99grad/10>`__ ❤️

Your contribution helps us maintain, improve, and add new features to this extension.