Alt generator REST API: requests and synchronization

A custom integration uploads images to the generator from your server, stores results in its own CMS and optionally synchronizes corrections with DockAccess. This guide describes the public mechanism used by CMS integrations. It needs neither an AI service administrator account nor keys embedded in the browser.

1. Prepare the account, domain and endpoint

1. Sign in to DockAccess or create an account, then verify your email address.
2. Open My sites, choose Add site and enter the production domain, without a protocol or path. For an existing site, open its configuration instead of creating a duplicate.
3. Enable ALT Generator for this site and save. A paused service must be resolved within the account’s site allowance before the plugin can generate.
4. Copy the site token from the site configuration. In the CMS connection form, enter that token and the login and password of the DockAccess account that owns it. Select Connect.
5. Check the connected status and site address, then generate one test alt before starting a batch. The plugin must also appear among this site’s connected integrations in DockAccess.

The site token identifies the website. It is different from the account API key and the connection secret. Enter DockAccess credentials, not your CMS administrator credentials. The official plugins use the password for the connection request and do not store it. If you normally use social sign-in and have no password, set one using the password reset flow first.

Prepare a public HTTPS endpoint for incoming alt updates. Restrict writes to signed requests as described below. Keep the account key and connection secret in protected server configuration. Do not put them in HTML, JavaScript, links or request logs.

2. Connect the installation

Send JSON to POST https://dockaccess.org/fast-api/integrations/connect. These values are examples; the login and password are for connecting, not credentials to retain for subsequent jobs.

{
  "token": "SITE_TOKEN",
  "login": "owner@example.com",
  "password": "DOCKACCESS_PASSWORD",
  "system": "custom-cms",
  "system_version": "1.0.0",
  "module_version": "1.0.0",
  "home_url": "https://example.com",
  "callback_url": "https://example.com/integrations/dockaccess/alts"
}
Copy text

On success, store external_token as the account key and integration.secret as the signing secret. The site token remains the website identifier. For 409 already_connected, show the existing connection and retry with overwrite: true only after the user decides to replace it. Replacement rotates the secret.

3. Verify the service before generating

Call POST https://dockaccess.org/fast-api/integrations/verify with {"token":"SITE_TOKEN","secret":"CONNECTION_SECRET"}. Continue only on success with alt_enabled: true. Also check token.alt_paused. A disconnected or inactive integration requires owner action, rather than repeated generation attempts.

4. Upload an image

The generator accepts POST https://alt.dockaccess.org/api/generate. Send the image as multipart/form-data in the file field, with options in the query string. Do not manually set Content-Type without the proper multipart boundary. Run the following example only in a trusted environment that does not log request URLs containing keys.

curl --request POST \
  "https://alt.dockaccess.org/api/generate?key=EXTERNAL_ACCOUNT_KEY&set_ref=SITE_TOKEN&lang=en&tone=neutral&variants=1" \
  --form 'file=@/srv/uploads/backpack.jpg;type=image/jpeg'
Copy text

key is the external account key, set_ref the site token, lang the description language and variants the number of proposals, from 1 to 3. Optional context is limited to 500 characters. URL-encode options, for example with http_build_query. A shared set_ref places one site’s images in its set; do not reuse a token across independent client websites.

The response contains data.set_uuid, data.image.uuid and data.image.alts, a list of {"alt":"…","locale":"en"} objects. Store the identifiers with the local image ID and language. Your system must persist the text before it can appear in img alt. Uploading the same filename and content again in the same set may replace the chosen language’s description and consumes the allowance again.

5. Usage and errors

GET https://alt.dockaccess.org/api/user?key=EXTERNAL_ACCOUNT_KEY returns requests.limit, requests.used, requests.period (day or month) and requests.resets_at in UTC. Do not derive the window’s end from the payment date.

• 429 with X-Alt-Reason: limit_reached: stop the batch, retain completed results and show the renewal time; X-Alt-Limit-Period identifies the window.
• 429 with X-Alt-Reason: rate_limited: wait according to Retry-After and retry that image. Do not hardcode a requests-per-minute value.
• 400, 413, 415: check the input, size and actual image format. Do not retry without correcting the file or options.
• 401 or 403: check the connection, key and permissions; show the problem to the owner.
• Service failure or a timeout after uploading: check the set before retrying. No response does not prove generation did not happen.

6. Synchronize manual corrections

Send a CMS edit to PUT https://dockaccess.org/fast-api/alts/update as JSON:

{
  "key": "EXTERNAL_ACCOUNT_KEY",
  "token": "SITE_TOKEN",
  "image_uuid": "11111111-2222-4333-8444-555555555555",
  "alts": [{"alt": "Green backpack with two front pockets", "locale": "en"}]
}
Copy text

Send corrections only for images owned by the account and linked to your system. Text is 1–2000 characters and the list allows up to 5 items. Retain other languages and variants that should survive: saving replaces the image’s list of alts with the submitted list.

7. Receive signed updates

The official plugins can receive JSON at the registered callback_url. Saving an alt in the account currently does not automatically deliver an update to that address. If you need synchronization in both directions, implement a sender and delivery retries as a separate part of your integration. The following contract describes receiving updates: the body contains token, an image_uuid or image_url, and the alts array. Verify the signature before decoding and writing data:

$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_DOCKACCESS_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_DOCKACCESS_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

if (!ctype_digit($timestamp)
    || abs(time() - (int) $timestamp) > 300
    || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
// Validate JSON, the site token, local image mapping, languages and text length.
// Save idempotently without sending this same change back to the API.
Copy text

The signature covers the exact body bytes: do not re-encode JSON before comparing it. Return 403 for a mismatched token, 404 for an unknown image, and 200 with {"success":true,"updated":1} after writing. Bound request size and restrict updates to your own images. Clean descriptions to plain text and escape them when rendering HTML.

8. Acceptance checks and disconnecting

1. Connect a test domain and generate one image in its content language.
2. Check local CMS storage, the account’s set and rendered HTML.
3. Edit locally and check the account. Test receiving with a separate signed request; if you add a sender, check both directions and the absence of loops.
4. Check rejection of a bad signature, old timestamp, foreign token and image, and batch stopping when the allowance is exhausted.
5. After disconnecting, confirm verification refuses further work while saved alts remain on the page.

Disconnecting from the application uses POST /fast-api/integrations/disconnect with token, login, password and home_url. The owner can also disconnect through the DockAccess account.

For PHP applications, the client library simplifies file checks and generation. See the generator user guide for editorial principles.