Table of Contents
AITiny will be unable to function properly if there are networking issues or outages which prevent you from connecting to, or using the AI service you have chosen. Always check if any such issues exist before asking for support.
All connections to AI services are proxied through your web server. The way this works, is that your browser makes a request to your web server. Your web server, subsequently, makes a request to the AI service. The result is read by your server, and returned to your browser.
While it sounds inefficient and complicated, there are several reasons why you want to do that. The most important is the API key used to access your AI service is not present in the HTML page where the editor is placed. This is a major security feature. Remember, if someone has your API key they can make requests to the AI service on your behalf. At best, they will make a lot of (very expensive) requests, leaving you to foot the bill. At worst, they can take over your account, or intercept your data.
Super Users and any other user group granted adequate access privileges in Joomla to configure plugins can see the API token in the plugin's configuration.
The API token is stored in your site's database. If your site is compromised in a way which allows reading from its database, the key will be exposed.
There are ways around that, documented under "Hiding your API keys using a web server".
That said, there are also drawbacks.
When you want to connect a live server with a locally hosted AI service you need some additional configuration. This is the obvious problem of your local network being, by default, inaccessible from the Internet. You will need to somehow make the AI service hosted on your computer / internal network accessible over the Internet. One option is to expose the locally hosted AI service directly to the Internet using port forwarding on your router. The other option is to use Ngrok, Expose, or a similar service to proxy and expose the locally hosted AI service to the Internet. Either way, AITiny will only work when your computer is online, the port forwarding / proxying is operational, and the locally hosted AI service is running. This kind of use case is only recommended for solo developers, or web agencies with a dedicated AI server.
Since the request is going through your web server, it is subject to a number of timeouts in the web server stack: PHP itself, the web server daemon's timeout waiting for PHP to send it back some data, the web server's timeout on processing requests, and the Operating System's maximum time per process (ulimit -t). These timeouts tend to be shorter and inflexible the cheaper your hosting tier is. In some cases when responses take longer, or when working with larger content, you may experience timeout issues. In some extreme cases the timeouts are so tight that you cannot use AITiny altogether. If this is the case, you have to talk to your host to find a solution. The solution may be switching to a more expensive hosting tier, or moving to a different host.
Many hosts apply transparent caching for all requests made from code running on your server to external sites, like AI services. Most of these hosts do it right, following the Internet RFCs to the letter; you won't have a problem with these hosts. Some hosts, however, violate the RFCs, caching replies when they MUST NOT do so. For example, we've seen hosts which cache replies with explicit no-cache or Authorization headers (explicitly forbidden by RFC 9111 3). In these cases your only option is to have your host respect the RFCs in their transparent caching, or move to a different host.
Proxying the request through your site requires a pristine, raw JSON (or raw text) reply. Third party plugins may break this reasonable expectation because they have programming mistakes (bugs). We have observed two main classes of bugs in third party plugins. First and foremost, the PHP core and even some carefully written plugins may generate PHP deprecation notices, notices, or warnings as they try to support a multitude of PHP versions. You can fix that by setting Error Reporting to None, and Debug Site to No in your Global Configuration; this is the recommended configuraiton for production sites anyway. Moreover, we have seen badly written plugins which violate Joomla best practices, breaking non-HTML output. The only solution to those problems is reporting the issue to their developer, and hope they fix it.
Some requests MAY fail due to security restrictions on your site. These may come from things under your control (.htaccess file, security extensions), partially under your control (third party services in front of your site, such as CloudFlare, Sucuri, etc), or completely outside your control (server security features such as Immunify360, Apache mod_security2 rules, etc). If it's something under your full or partial control you can work around with varying degrees of effort and guidance by the developers of the security software and/or services you are using. If it's caused by your host's security measures you will have to talk to your host and find a solution. It is usually possible, albeit it often requires escalation to a second or third level of technical support.
Finally, if you are using the Streaming option you may or may not get a properly streaming reply. This depends entirely on your hosting stack. If your host is using a transparent caching proxy for requests made from your server to external resources, or has configured the web server daemon to enforce caching there is nothing you or us can do about it, and it's unlikely your host will change that configuration just for you.
The rule of thumb is that if you are using a good quality host, and extensions by reputable extension developers you will not hit most of these problems. If you do, both your host and the extension developers can very likely help you overcome these problems.
If you want to use a commercial AI service without exposing your API key even to Super Users, there are ways to do that. Please note that whether these will work for you relies entirely on your server configuration. If you are unsure, please do ask your host.
The idea is that you can set up a proxy subdomain or URL which proxies a request to the AI service, adding the API key. This way, your API key remains hidden from everyone, including your Super Users.
If you are using the Apache web server and you do not have access to your server and/or VirtualHost configuration –as is the typical case on commercial hosting– you can use the second Apache option described under Using A Subdirectory, the one with just two lines you add to your .htaccess file.
Since you are proxying the requests through your web server, they are subject to server-specific timeouts, caching issues, and security controls.
Your web server, or the Operating System of your host may impose a timeout which prevents you from using the AI service for requests that take longer; this may be as low as 5 seconds on some restrictive servers.
If you have a security service in front of your site, or your host applies security controls on the server, these will also apply.
This method is best used on servers under your extended or full control such as VPS, managed servers, cloud hosting / VMs, and dedicated (bare metal) servers.
The way to go about it depends on which web server you are using, and whether you want to use a subdomain or a subdirectory to proxy your requests.
Use case: Your site is https://www.example.com. You want to set up the subdomain ai.example.com to proxy your requests to the AI service. The API endpoint of the AI service you are using is https://api.openai.com/ (OpenAI) and your API key for it is sk-YourOpenAIKeyHere.
You need to create a new VirtualHost configuration like so:
<VirtualHost *:80> ServerName ai.example.com # Ensure required modules are enabled: # a2enmod proxy proxy_http headers ProxyPreserveHost On ProxyPass / https://api.openai.com/ ProxyPassReverse / https://api.openai.com/ RequestHeader set Authorization "Bearer sk-YourOpenAIKeyHere" # Add your SSL configuration here. The following lines are just an example. SSLEngine on SSLCertificateFile /path/to/your/cert.pem SSLCertificateKeyFile /path/to/your/key.pem</VirtualHost>
This code WILL NOT work inside a .htaccess site. Virtual host configuration files MUST be included by the server configuration file.
Create a new server block, like so:
server { listen 443 ssl; server_name ai.example.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass https://api.openai.com/; proxy_set_header Host api.openai.com; proxy_set_header Authorization "Bearer sk-YourOpenAIKeyHere"; }}This code WILL NOT work inside another server block. This is what you can usually modify on commercial hosting which allows you to change your NginX configuration.
Here are the changes you need to make to your AITiny configuration to use this custom endpoint:
AI Service: Custom
Endpoint URL: https://ai.example.com
API Key / Token: (leave blank)
Use case: Your site is https://www.example.com. You want to set up the subdirectory https://www.example.com/ai to proxy your requests to the AI service. The API endpoint of the AI service you are using is https://api.openai.com/ (OpenAI) and your API key for it is sk-YourOpenAIKeyHere.
Change the VirtualHost configuration for your www.example.com domain name, adding the following before any other Location directives (if any):
<Location /ai> ProxyPass https://api.openai.com/ ProxyPassReverse https://api.openai.com/ RequestHeader set Authorization "Bearer sk-YourOpenAIKeyHere"</Location>
This code WILL NOT work inside a .htaccess site. As per Apache's documentation it only works in the server and virtual host configuration files.
Another option which DOES WORK WITH .htaccess FILES is to use RewriteRule directives to your VirtualHost configuration or your Joomla! .htaccess file:
RewriteRule ^/ai/(.*)$ https://api.openai.com/$1 [P]RequestHeader set Authorization "Bearer sk-YourOpenAIKeyHere"
If you are using Admin Tools' .htaccess Maker you can add these lines in the “Custom .htaccess rules at the top of the file” area, under the Custom .htaccess rules header. Remember to click on Save And Create .htaccess in the toolbar to apply these changes.
If you are using Admin Tools Professional's .htaccess Maker we strongly advise you to also enable its Main Password feature to prevent everyone else, including other Super Users, from being able to see the .htaccess Maker configuration. Remember, your API key will be stored in the .htaccess Maker configuration.
This method will work as long as the proxy, proxy_http, headers, and rewrite Apache modules are enabled in your Apache server configuration. These are enabled on most servers. Otherwise, you can ask your host to enable them for you, explaining the use case — showing them this documentation page will very likely help.
Add the following code in your server block, before any other location blocks:
location /ai/ { proxy_pass https://api.openai.com/; proxy_set_header Host api.openai.com; proxy_set_header Authorization "Bearer sk-YourOpenAIKeyHere"; # Remove /ai prefix before sending to the AI service rewrite ^/ai/(.*)$ /$1 break;}Here are the changes you need to make to your AITiny configuration to use this custom endpoint:
AI Service: Custom
Endpoint URL: https://www.example.com/ai
API Key / Token: (leave blank)