Endpointy

Kanonicznym kontraktem jest YAML OpenAPI 3.1. Ta strona podsumowuje każdą trasę w pigułce; zajrzyj do specyfikacji po pełne schematy, przykłady i odpowiedzi błędów.

Tożsamość

GET /me

Zwraca instalację wywołującego, konto sprzedawcy, efektywne scope, limit zapytań i aktualną listę subprocesorów.

Scope: dowolny ważny klucz.

Zadania

POST /jobs

Prześlij pojedyncze zadanie generowania. Body zgodne z SubmitJobRequest w specyfikacji OpenAPI.

Scope: plugin.jobs:create. Idempotencja: obsługiwana.

POST /jobs/batch

Prześlij do 50 zadań w jednym wywołaniu (konfigurowalne przez PLUGIN_API_BATCH_LIMIT); per-itemowe wyniki w odpowiedzi.

Scope: plugin.jobs:create. Idempotencja: nie obsługiwana w v1; wysyłaj pojedynczo przez POST /jobs z własnym Idempotency-Key, jeśli potrzebujesz replay-safe ponowień.

GET /jobs

Lista zadań w zasięgu wywołującej instalacji. Query: status, created_after, created_before, limit (max 100), cursor.

Scope: plugin.jobs:read.

GET /jobs/{id}

Pobierz jedno zadanie. Outputy zawierają presigned URLs ważne 7 dni; użyj POST /jobs/{id}/refresh-url, by wystawić świeże.

Scope: plugin.jobs:read.

POST /jobs/{id}/refresh-url

Wybij świeży presigned URL dla wcześniej ukończonego outputu. Użyj, gdy istniejący URL wygasł.

Scope: plugin.jobs:read. Zwraca 409 job_not_completed, jeśli zadanie wciąż pending.

DELETE /jobs/{id}

Anuluj oczekujące zadanie i zwróć rezerwację kredytową. Zwraca 409 job_not_cancelable, gdy zadanie osiągnęło completed/failed.

Scope: plugin.jobs:cancel.

Assety

POST /assets/upload

Wybij presigned upload URL dla asset źródłowego (surowe zdjęcie produktu do przetworzenia). Wyślij bajty bezpośrednio na zwrócony URL przez PUT.

Scope: plugin.assets:upload.

Presety

GET /presets

Lista presetów widocznych dla sprzedawcy — zarówno zapisane account-scoped, jak i Qamera-curated.

Scope: plugin.jobs:read (lista presetów jedzie na scope read-jobs; w v1 nie ma dedykowanego scope dla presetów).

Lifecycle instalacji

POST /installations/{id}/rotate-hmac

Obróć sekret HMAC webhook. Poprzedni sekret pozostaje ważny przez 48h, by deliveries in flight nie failowały. Response zawiera nowy sekret raz.

Scope: plugin.installations.manage.

Webhooki

POST /webhooks/{delivery_id}/replay

Ponownie zakolejkuj delivery webhook dla zadania. Użyj, gdy Twój endpoint był down podczas oryginalnego okna ponowień.

Scope: plugin.webhooks:manage. Delivery musi należeć do wywołującej instalacji.