Referencja narzędzi

Twój asystent AI zobaczy te narzędzia, gdy połączysz go z Qamera AI za pomocą klucza API. Pogrupowaliśmy je według zadania, przy którym się przydają, a nie według budowy serwera.

Nie wywołujesz ich samodzielnie. Opisujesz, czego potrzebujesz, a asystent dobiera narzędzie i uzupełnia parametry. Ta lista jest po to, żebyś wiedział, co jest możliwe — i żebyś mógł być precyzyjny tam, gdzie to ma znaczenie: przy wyborze presetu, liczby ujęć czy proporcji kadru.

Zanim zaczniesz

Dwa zakresy uprawnień. Większość narzędzi wymaga zakresu content.register na kluczu API. Dwa narzędzia od statusu zamówień na końcu tej strony wymagają content.read. Jeśli utworzysz klucz tylko z jednym z nich, większość pracy asystenta się powiedzie, a sprawdzanie statusu będzie zwracać błąd — w Konfiguracji opisujemy, jak zaznaczyć oba.

Listy zwracają najnowsze pozycje i mają limit. Sześć list z treścią — produkty, modele, scenerie, zdjęcia z sesji, packshoty i filmy — przyjmuje limit (od 1 do 500, domyślnie 50). Dwa narzędzia odbiegają od tej reguły: list_recent_generations przyjmuje limit od 1 do 50 z domyślną wartością 20, a get_presets przyjmuje maxRecords zamiast limit, domyślnie 20. Każdy wpis niżej podaje własne zakresy.

Jeśli serwer musiał skrócić listę, w odpowiedzi pojawia się blok truncated z informacją, ile pozycji przyszło i jak zawęzić wyszukiwanie. Brak tego bloku oznacza, że nic nie zostało obcięte po drodze do asystenta.

Listy nie zawierają zdjęć. Zwracają identyfikatory, nazwy i statusy. Żeby asystent mógł naprawdę spojrzeć na zdjęcie, korzysta z jednego z dwóch narzędzi podglądu — te zwracają sam obraz.

Generowanie kosztuje kredyty. Wszystko, co nazywa się register_…, składa zamówienie. Przeglądanie list, podglądy i ocenianie są bezpłatne.

Produkty

Produkt to jedno lub kilka zdjęć tej samej rzeczy, wgranych do Twojego workspace'u. Wszystko pozostałe — packshoty, sesje zdjęciowe, filmy — powstaje na podstawie produktu.

register_product

Wgrywa zdjęcia i rejestruje je jako jeden produkt. To pierwszy krok każdego generowania: bez produktu nie ma z czego generować.

Parametry:

• images (tablica, wymagany) — od 1 do 10 adresów zdjęć (http lub https). Wszystkie tworzą jeden produkt, a nie po jednym produkcie każde.
• name (tekst, opcjonalny) — nazwa produktu, na przykład „Koszula lniana, ecru".
• productType (tekst, opcjonalny) — kategoria, na przykład „stroje kąpielowe".

Zwraca: zarejestrowany produkt wraz z identyfikatorem, którego używa każdy kolejny krok.

Dwie rzeczy warte zapamiętania. Produkt nie jest gotowy do generowania w chwili, gdy narzędzie zwraca odpowiedź — platforma najpierw analizuje zdjęcia, a status przechodzi UPLOADED → DESCRIBING → DESCRIBED. Asystent sprawdzi to przez get_products. Poza tym dwukrotne wywołanie na tym samym zdjęciu utworzy dwa produkty, bo każde wgranie jest traktowane jako nowy materiał.

get_products

Wyświetla produkty w Twoim workspace, od najnowszych.

Parametry:

• limit (liczba całkowita, opcjonalny) — od 1 do 500, domyślnie 50.

Zwraca: identyfikator, nazwę, status i datę utworzenia każdego produktu.

update_product

Poprawia nazwę lub kategorię produktu. Niczego nie generuje i nie kosztuje kredytów.

Parametry:

• productId (tekst, wymagany) — identyfikator produktu.
• name (tekst, opcjonalny) — poprawiona nazwa.
• productType (tekst, opcjonalny) — poprawiona kategoria.

Modele

Modele to generowane przez AI postacie, które mogą prezentować Twój produkt.

get_models

Wyświetla modele dostępne w Twoim workspace.

Parametry:

• statusFilter (tekst, opcjonalny) — all (domyślnie) albo approved.
• limit (liczba całkowita, opcjonalny) — od 1 do 500, domyślnie 50.

register_models

Generuje nowe modele na podstawie opisu. Kosztuje kredyty.

Parametry:

• preferences (tekst, wymagany) — jak mają wyglądać modele, na przykład „kobieta, 25–30 lat, naturalny makijaż, swobodna poza".
• count (liczba całkowita, opcjonalny) — od 1 do 10, domyślnie 10.

Scenerie

Scenerie to generowane przez AI tła, na których umieszczany jest produkt.

get_sceneries

Wyświetla scenerie dostępne w Twoim workspace.

Parametry:

• statusFilter (tekst, opcjonalny) — all (domyślnie) albo approved.
• limit (liczba całkowita, opcjonalny) — od 1 do 500, domyślnie 50.

register_sceneries

Generuje nowe scenerie na podstawie opisu. Kosztuje kredyty.

Parametry:

• preferences (tekst, wymagany) — tło, jakiego oczekujesz, na przykład „betonowy taras w popołudniowym słońcu".
• count (liczba całkowita, opcjonalny) — od 1 do 10, domyślnie 10.

Sesje zdjęciowe

Sesja zdjęciowa umieszcza produkt w scenerii — opcjonalnie z modelem — i tworzy zestaw zdjęć do Twojej oceny.

register_photo_shoot

Zamawia sesję zdjęciową. Kosztuje kredyty.

Parametry:

• productId (tekst, wymagany) — produkt do sfotografowania.
• aspectRatio (tekst, wymagany) — jedna z wartości: match_input, 9:16, 16:9, 1:1, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 21:9.
• modelId (tekst, opcjonalny) — model, który ma wystąpić.
• sceneryId (tekst, opcjonalny) — tło.
• presetId (tekst, opcjonalny) — preset stylu, którego ma się trzymać generowanie.
• industry (tekst, opcjonalny) — branża produktu, na przykład „moda".
• suggestions (tekst, opcjonalny) — wskazówki własnymi słowami, na przykład „miękkie światło dzienne, ujęcie lekko z góry".
• count (liczba całkowita, opcjonalny) — od 1 do 20 zdjęć.

Zwraca: identyfikator zamówienia. Generowanie trwa w tle — postęp śledzi check_generation_status.

get_images

Wyświetla zdjęcia powstałe w sesjach zdjęciowych.

Parametry:

• statusFilter (tekst, opcjonalny) — all (domyślnie) albo approved.
• productId (tekst, opcjonalny) — tylko zdjęcia jednego produktu.
• orderId (tekst, opcjonalny) — tylko zdjęcia z jednego zamówienia.
• limit (liczba całkowita, opcjonalny) — od 1 do 500, domyślnie 50.

get_image_preview

Zwraca jedno zdjęcie, żeby asystent mógł je faktycznie zobaczyć i skomentować.

Parametry:

• recordId (tekst, wymagany) — identyfikator zdjęcia.
• tier (tekst, opcjonalny) — medium (około 1024 px, domyślnie) albo full (oryginał).

update_image

Zapisuje Twoją ocenę jednego zdjęcia z sesji.

Parametry:

• recordId (tekst, wymagany) — identyfikator zdjęcia.
• voting (tekst, wymagany) — accepted, rejected albo pending, żeby wycofać wcześniejszą ocenę.

Zwróć uwagę na nazewnictwo. Zdjęcia z sesji używają wartości accepted / rejected, a packshoty APPROVED / REJECTED. To dwa osobne słowniki i nie są wymienne.

Packshoty

Packshot to czyste zdjęcie produktu, zwykle na jednolitym tle, przeznaczone na kartę produktu w sklepie.

register_packshots

Zamawia generowanie packshotów. Kosztuje kredyty.

Parametry:

• productId (tekst, wymagany) — produkt do sfotografowania.
• presetId (tekst, opcjonalny) — preset stylu.
• sceneryId (tekst, opcjonalny) — tło.
• modelId (tekst, opcjonalny) — model.
• count (liczba, opcjonalny) — domyślnie 10, maksymalnie 50.

Zwraca: identyfikator zamówienia.

get_packshots

Wyświetla wygenerowane packshoty.

Parametry:

• statusFilter (tekst, opcjonalny) — all (domyślnie) albo approved.
• orderId (tekst, opcjonalny) — tylko packshoty z jednego zamówienia.
• limit (liczba całkowita, opcjonalny) — od 1 do 500, domyślnie 50.

get_packshot_preview

Zwraca jeden packshot jako obraz, żeby asystent mógł go ocenić, zanim go zatwierdzisz.

Parametry:

• recordId (tekst, wymagany) — identyfikator packshotu.

update_packshot

Zapisuje Twoją ocenę packshotu albo przenosi go do archiwum.

Parametry:

• recordId (tekst, wymagany) — identyfikator packshotu.
• voting (tekst, opcjonalny) — APPROVED albo REJECTED.
• status (tekst, opcjonalny) — ARCHIVE, żeby zarchiwizować packshot.

Filmy

register_video

Generuje krótki film na podstawie jednego zdjęcia, które już masz. Kosztuje kredyty.

Parametry:

• generatedImageId (tekst, opcjonalny) — zdjęcie z sesji zdjęciowej.
• imageId (tekst, opcjonalny) — zdjęcie z Twojej biblioteki.
• suggestion (tekst, opcjonalny) — wskazówka dla AI, na przykład „powolne najechanie, produkt pozostaje na środku".
• provider (tekst, opcjonalny) — dostawca generowania wideo; zostaw pusty, jeśli nie masz powodu, by go zmieniać.

Wymagany jest jeden z parametrów: generatedImageId albo imageId.

get_videos

Wyświetla wygenerowane filmy wraz z adresem gotowego pliku.

Parametry:

• limit (liczba całkowita, opcjonalny) — od 1 do 500, domyślnie 50.

Presety

Preset to zapisany styl: wskazówki, którymi kieruje się generowanie w kwestii jakości i ilości. Katalog jest wspólny, więc presety przygotowane przez Qamera AI są dostępne w każdym workspace obok tych, które utworzysz samodzielnie.

get_presets

Wyświetla presety z polami potrzebnymi do wyboru: identyfikator, nazwa, informacja o tym, czy wymagana jest sceneria, kategoria i tagi. Długie teksty wskazówek są celowo pominięte — kompletny katalog nie zmieściłby się w jednej odpowiedzi.

Parametry:

• maxRecords (liczba, opcjonalny) — domyślnie 20.

Pole scenery ma znaczenie. required oznacza, że bez scenerii preset nie da sensownego wyniku. recommended oznacza, że w razie braku zostanie użyta wartość domyślna. null oznacza, że nikt jeszcze tego presetu nie przejrzał — traktuj to jako brak informacji, a nie jako „sceneria niepotrzebna".

get_preset

Zwraca jeden preset w całości, razem z tekstami wskazówek, których nie ma w get_presets.

Parametry:

• presetId (tekst, wymagany) — identyfikator presetu, skopiowany bez zmian z get_presets.

create_preset

Tworzy preset należący do Twojego workspace'u.

Parametry:

• name (tekst, wymagany)
• quantityGuidelines (tekst, wymagany) — ile materiału i w jakiej różnorodności ma powstać.
• qualityGuidelines (tekst, wymagany) — jak wygląda dobry wynik.

update_preset

Aktualizuje preset należący do Twojego workspace'u. Presetów wspólnych nie można edytować.

Parametry:

• presetId (tekst, wymagany)
• name (tekst, opcjonalny)
• quantityGuidelines (tekst, opcjonalny)
• qualityGuidelines (tekst, opcjonalny)
• existingGalleryIds (tablica, opcjonalny) — załączniki galerii, które mają zostać.
• removeCover (wartość logiczna, opcjonalny) — ustaw true, żeby usunąć zdjęcie okładkowe.

Zamówienia i status

Każde narzędzie register_… zwraca identyfikator zamówienia. Te dwa narzędzia śledzą, co się z nim stało. Oba wymagają zakresu content.read na kluczu API.

check_generation_status

Pokazuje jedno zamówienie w szczegółach.

Parametry:

• orderId (tekst, wymagany) — identyfikator zwrócony przez narzędzie register_….

Zwraca: stan całego zamówienia — pending, in_progress, completed, failed albo cancelled — rozbicie na poszczególne zadania wraz z użytym modelem i ewentualnym błędem, adresy gotowych plików oraz znaczniki czasu.

list_recent_generations

Wyświetla ostatnie zamówienia, od najnowszych. Przydaje się, gdy identyfikator zamówienia gdzieś przepadł.

Parametry:

• status (tekst, opcjonalny) — pending, in_progress, completed, failed albo cancelled.
• limit (liczba całkowita, opcjonalny) — od 1 do 50, domyślnie 20.
• since (tekst, opcjonalny) — znacznik czasu ISO 8601; tylko zamówienia utworzone po nim.

Zwraca: podsumowanie każdego zamówienia. Po szczegóły jednego zamówienia i po adresy plików sięgnij do check_generation_status.