REST API generatora altów: żądania i synchronizacja

Własna integracja wysyła obrazy do generatora po stronie serwera, zapisuje wynik w swoim CMS-ie i opcjonalnie synchronizuje poprawki z DockAccess. Poniżej opisujemy publiczny mechanizm używany przez integracje CMS. Nie wymaga on konta administratora usługi AI ani umieszczania kluczy w przeglądarce.

1. Przygotuj konto, domenę i endpoint

1. Zaloguj się do DockAccess lub załóż konto, a następnie potwierdź adres e-mail.
2. Otwórz Moje strony, wybierz Dodaj stronę i wpisz domenę produkcyjną, bez protokołu i ścieżki. Jeżeli strona już istnieje, otwórz jej konfigurację zamiast tworzyć duplikat.
3. Włącz Generator ALT dla tej strony i zapisz zmiany. Jeżeli usługa jest wstrzymana, najpierw rozwiąż problem z limitem stron na koncie.
4. Skopiuj token strony z jej konfiguracji. W formularzu połączenia w CMS-ie podaj ten token oraz login i hasło konta DockAccess, do którego należy strona. Wybierz Połącz.
5. Sprawdź status połączenia i adres strony, a następnie wygeneruj jeden opis próbny przed uruchomieniem większej partii. Wtyczka powinna być też widoczna wśród połączonych integracji tej strony w DockAccess.

Token strony identyfikuje witrynę. Różni się od klucza API konta i sekretu połączenia. Podaj dane logowania do DockAccess, a nie dane administratora CMS-a. Oficjalne wtyczki używają hasła przy żądaniu połączenia i go nie zapisują. Jeżeli logujesz się przez konto społecznościowe i nie masz hasła, najpierw ustaw je przez odzyskiwanie hasła.

Przygotuj publiczny endpoint HTTPS przyjmujący aktualizacje altów. Dostęp do jego zapisu ogranicz do podpisanych żądań opisanych poniżej. Własny serwer przechowuje klucz konta i sekret połączenia w chronionej konfiguracji. Nie umieszczaj ich w HTML, JavaScripcie, adresach linków ani logach żądań.

2. Połącz instalację

Wyślij POST https://dockaccess.org/fast-api/integrations/connect z JSON-em. Dane poniżej są przykładowe; login i hasło służą do połączenia, nie zapisuj ich jako poświadczeń późniejszych zadań.

{
  "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"
}
Skopiuj tekst

Po sukcesie zapisz external_token jako klucz konta oraz integration.secret jako sekret podpisu. Token strony pozostał identyfikatorem witryny. Przy 409 already_connected pokaż użytkownikowi istniejące połączenie; dopiero po jego decyzji ponów żądanie z overwrite: true. Zastąpienie obraca sekret.

3. Weryfikuj usługę przed generowaniem

Wywołaj POST https://dockaccess.org/fast-api/integrations/verify z {"token":"SITE_TOKEN","secret":"CONNECTION_SECRET"}. Kontynuuj tylko po sukcesie i przy alt_enabled: true. Sprawdź również token.alt_paused. Rozłączone lub nieaktywne połączenie wymaga działania właściciela, a nie powtarzania generowania.

4. Prześlij obraz

Generator przyjmuje POST https://alt.dockaccess.org/api/generate. Plik wysyłaj jako multipart/form-data w polu file; parametry umieść w query string. Nie ustawiaj ręcznie nagłówka Content-Type bez poprawnej granicy multipart. Poniższy przykład uruchamiaj wyłącznie w zaufanym środowisku, które nie zapisuje adresów żądań z kluczem.

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

key to zewnętrzny klucz konta, set_ref to token strony, lang to język opisu, variants to liczba propozycji od 1 do 3, a opcjonalny context ma maksymalnie 500 znaków. Parametry koduj jako URL, np. przez http_build_query. Wspólny set_ref umieszcza obrazy jednej witryny w jej zestawie; nie używaj jednego tokenu dla niezależnych stron klientów.

Odpowiedź zawiera data.set_uuid, data.image.uuid i data.image.alts, czyli listę obiektów {"alt":"…","locale":"pl"}. Zapisz identyfikatory wraz z lokalnym identyfikatorem obrazu i językiem. Dopiero trwały zapis w Twoim systemie pozwala wyświetlić opis w img alt. Powtórzenie przesłania takiej samej nazwy i zawartości w tym samym zestawie może zastąpić opis w wybranym języku i ponownie zużywa limit.

5. Zużycie i błędy

GET https://alt.dockaccess.org/api/user?key=EXTERNAL_ACCOUNT_KEY zwraca requests.limit, requests.used, requests.period (day lub month) i requests.resets_at w UTC. Nie wyliczaj końca okresu na podstawie daty płatności.

• 429 i X-Alt-Reason: limit_reached: zatrzymaj partię, zachowaj wyniki i pokaż termin odnowienia; okres limitu określa X-Alt-Limit-Period.
• 429 i X-Alt-Reason: rate_limited: odczekaj zgodnie z Retry-After i ponów ten obraz. Nie ustalaj na stałe liczby żądań na minutę.
• 400, 413, 415: sprawdź dane, rozmiar i rzeczywisty format obrazu. Nie ponawiaj bez zmiany pliku lub parametrów.
• 401 lub 403: sprawdź połączenie, klucz i uprawnienia; pokaż błąd właścicielowi.
• Awaria usługi lub timeout po wysłaniu pliku: sprawdź stan zestawu przed ponowieniem. Brak odpowiedzi nie dowodzi, że generowanie nie zostało wykonane.

6. Synchronizuj ręczne poprawki

Zmianę ze swojego CMS-a wyślij przez PUT https://dockaccess.org/fast-api/alts/update z JSON-em:

{
  "key": "EXTERNAL_ACCOUNT_KEY",
  "token": "SITE_TOKEN",
  "image_uuid": "11111111-2222-4333-8444-555555555555",
  "alts": [{"alt": "Zielony plecak z dwiema kieszeniami z przodu", "locale": "pl"}]
}
Skopiuj tekst

Wysyłaj poprawki wyłącznie dla obrazów należących do konta i powiązanych z Twoim systemem. Tekst ma od 1 do 2000 znaków, a lista obejmuje najwyżej 5 pozycji. Zachowuj pozostałe języki i warianty, które mają zostać utrzymane: zapis zastępuje przekazaną listę altów obrazu.

7. Odbieraj podpisane aktualizacje

Oficjalne wtyczki mają przygotowany odbiór JSON-a pod zarejestrowanym callback_url. Obecny zapis altu na koncie nie wywołuje automatycznej wysyłki do tego adresu. Jeżeli budujesz dwukierunkową synchronizację, dodaj nadawcę i ponawianie dostarczenia jako osobną część integracji. Poniższy kontrakt opisuje obsługę odbioru: treść obejmuje token, identyfikator image_uuid lub image_url oraz tablicę alts. Zweryfikuj podpis przed dekodowaniem i zapisaniem danych:

$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;
}
// Sprawdź JSON, token strony, lokalne powiązanie obrazu, języki i długość tekstu.
// Zapisz wynik idempotentnie, bez ponownego wysyłania tej samej zmiany do API.
Skopiuj tekst

Podpis obejmuje dokładne bajty treści: nie koduj JSON-a ponownie przed porównaniem. Dla niepasującego tokenu zwróć 403, nieznanego obrazu 404, a po zapisie 200 z {"success":true,"updated":1}. Ogranicz rozmiar żądania i przypisuj aktualizacje wyłącznie do własnych obrazów. Tekst czyść do zwykłego tekstu i escapuj dopiero w miejscu renderowania HTML.

8. Test odbiorczy i rozłączenie

1. Połącz domenę testową i wygeneruj jeden obraz w języku treści.
2. Sprawdź zapis w lokalnym CMS-ie, zestaw na koncie i wynikowy HTML.
3. Zmień tekst lokalnie i sprawdź zapis na koncie. Odbiór przetestuj osobnym podpisanym żądaniem; jeżeli dodasz własnego nadawcę, sprawdź obie strony i brak zapętlenia.
4. Sprawdź odmowę błędnego podpisu, stary timestamp, obcy token i obraz oraz zatrzymanie partii po wyczerpaniu puli.
5. Po rozłączeniu integracji potwierdź, że weryfikacja odmawia dalszej pracy, a zapisane alty pozostają na stronie.

Rozłączenie z aplikacji korzysta z POST /fast-api/integrations/disconnect i danych token, login, password, home_url. Właściciel może też rozłączyć integrację na koncie DockAccess.

Jeżeli Twoja aplikacja korzysta z PHP, biblioteka klienta upraszcza sprawdzanie plików i generowanie. Zasady redakcyjne opisuje poradnik obsługi generatora.