Skip to content

Zarządzanie plikami za pomocą API Token ​

Zarządzanie plikami za pomocą API Token jest przeznaczone dla skryptów, zadań automatyzacji i zewnętrznych paneli administracyjnych. Używa uprawnienia manage, aby bez otwierania panelu administracyjnego edytować informacje o plikach, przenosić pliki, zmieniać ich nazwy, tworzyć pliki zastępcze katalogów, dostosowywać tagi plików i status listy, blokować albo przywracać możliwość przesyłania z danego IP oraz tworzyć lub usuwać krótkoterminowe Tokeny przesyłania.

Ten skrypt obsługuje tylko lekkie działania w zarządzaniu plikami i zarządzaniu użytkownikami. Przesyłanie, listowanie, usuwanie, ustawienia przesyłania, ustawienia witryny i relacje federacji nadal korzystają z własnych skryptów.

Edycja API Token

Przygotowanie ​

W panelu administracyjnym otwórz:

System Settings -> Security Settings -> API Token

Podczas tworzenia lub edycji API Token upewnij się, że Token ma pozwolenie na zarządzanie. Uprawnienie manage może zmieniać stan plików, stan przesyłania użytkowników i tworzyć krótkoterminowe Tokeny przesyłania, dlatego przyznawaj je tylko zaufanym skryptom lub zaufanym użytkownikom.

Operacje zapisu w skrypcie zarządzania plikami domyślnie działają w trybie podglądu i nie zapisują rzeczywistych zmian. Po sprawdzeniu podglądu dodaj --apply, aby wykonać zapis.

Token możesz także umieścić w zmiennej środowiskowej:

powershell
$env:IMGHOST_API_TOKEN="your API Token"

Pobieranie skryptu ​

SkryptZastosowanie
skrypt zarządzania plikamiMetadane plików, etykiety moderacji, tagi plików, status listy, przenoszenie, zmiana nazwy, tworzenie folderów, blokowanie/przywracanie IP oraz tworzenie i usuwanie krótkoterminowych Tokenów przesyłania

Wymagany jest Node.js 18 lub nowszy zainstalowany lokalnie.

Granice funkcji ​

MożliwośćSkryptUprawnienie
Przesyłanie plikówimghost-token-single-upload.mjs / imghost-token-chunk-upload.mjsupload
Listowanie plików, filtrowanie plików i odczyt statystyk użytkownikówimghost-token-list.mjslist
Usuwanie jednoznacznie wskazanych plikówimghost-token-delete.mjsdelete
Edycja informacji o plikach, tagów i list, przenoszenie, zmiana nazwy, tworzenie folderów, blokowanie IP oraz tworzenie lub usuwanie krótkoterminowych Tokenów przesyłaniaimghost-token-manage.mjsmanage
Edycja kanałów przesyłania, ustawień bezpieczeństwa, ustawień stron, innych ustawień i relacji federacjiSkrypty zarządzania konfiguracjąmanage

imghost-token-manage.mjs nie przesyła plików, nie listuje plików i nie usuwa plików. Jeśli musisz znaleźć fileId, najpierw użyj skryptu listowania do przefiltrowania plików. Jeśli musisz usunąć plik, przekaż konkretny fileId do skryptu usuwania.

Parametry ogólne ​

ParametrWymaganyOpis
--base-url <url>TakAdres ImgHost, np. https://image.ai6.me
--token <token>TakAPI Token; można użyć zmiennej środowiskowej IMGHOST_API_TOKEN
--retries <n>NieLiczba ponowień przy błędach tymczasowych; domyślnie 3
--timeout-ms <n>NieLimit czasu jednego żądania; domyślnie 180000
--output <pretty|json>NieFormat wyjścia; domyślnie pretty. Do wywołań programowych zalecany jest json
--save-response <path>NieZapisuje końcowy wynik jako plik JSON
--batch-size <n>NieLiczba elementów przetwarzanych w jednym żądaniu wsadowym; domyślnie 15, maksymalnie 15
--applyNieFaktycznie wykonuje zapis; bez tej opcji pokazuje tylko podgląd
-h / --helpNiePokazuje pomoc skryptu

Najpierw potwierdź fileId ​

Większość działań skryptu zarządzania plikami wymaga fileId. Możesz najpierw sprawdzić go skryptem listowania:

powershell
node imghost-token-list.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --files `
  --dir "test4" `
  --count 10 `
  --output json

Pole name w wyniku zwykle jest fileId, który można przekazać do skryptu zarządzania plikami.

Metadane pliku ​

Metadane pliku służą do zmiany nazwy wyświetlanej w zarządzaniu plikami panelu oraz źródła odczytu.

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --set-metadata `
  --file-id "photos/2026/a.jpg" `
  --file-name "cover.jpg" `
  --read-source backup

Po potwierdzeniu, że podgląd jest poprawny, zapisz zmianę:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --set-metadata `
  --file-id "photos/2026/a.jpg" `
  --file-name "cover.jpg" `
  --read-source backup `
  --apply

Parametry metadanych pliku ​

ParametrOpis
--set-metadataZmienia metadane jednego pliku
--file-id <id>ID pliku do zmiany
--file-name <name>Nowa nazwa wyświetlana w panelu
--read-source <primary|backup>Źródło odczytu. primary oznacza źródło główne, a backup źródło zapasowe

Podaj co najmniej jeden parametr: --file-name albo --read-source.

Etykiety moderacji ​

Etykiety moderacji odpowiadają klasyfikacji wiekowej pliku. Możesz najpierw odczytać bieżącą etykietę, a następnie ją zmienić.

Odczyt etykiety moderacji:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --get-label `
  --file-id "photos/2026/a.jpg"

Ustawienie etykiety moderacji:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --set-label `
  --file-id "photos/2026/a.jpg" `
  --label r12 `
  --apply

Parametry etykiet moderacji ​

ParametrOpis
--get-labelOdczytuje etykietę moderacji jednego pliku
--set-labelZmienia etykietę moderacji jednego pliku
--file-id <id>ID pliku
--label <value>Wartość etykiety: all-ages, r12, r16, r18, None

Tagi plików ​

Tagi plików służą do dodawania wyszukiwalnych tagów biznesowych do plików. Skrypt obsługuje odczyt, nadpisanie, dodawanie i usuwanie tagów, a także przetwarzanie wielu plików wsadowo.

Odczyt tagów pliku:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --get-tags `
  --file-id "photos/2026/a.jpg"

Dodawanie tagów:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --add-tags `
  --file-id "photos/2026/a.jpg" `
  --tag "cover" `
  --tag "2026" `
  --apply

Usuwanie tagów:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --remove-tags `
  --file-id "photos/2026/a.jpg" `
  --tag "cover" `
  --apply

Nadpisanie tagów:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --set-tags `
  --file-id "photos/2026/a.jpg" `
  --tag "archive" `
  --tag "public" `
  --apply

Dodawanie tagów wsadowo:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --batch-tags `
  --file-id "photos/2026/a.jpg" `
  --file-id "photos/2026/b.jpg" `
  --tag-action add `
  --tag "batch-test" `
  --apply

Parametry tagów plików ​

ParametrOpis
--get-tagsOdczytuje tagi jednego pliku
--set-tagsNadpisuje tagi jednego pliku
--add-tagsDodaje tagi do jednego pliku
--remove-tagsUsuwa tagi z jednego pliku
--batch-tagsUstawia, dodaje albo usuwa tagi wsadowo
--file-id <id>ID pliku; w działaniach wsadowych można przekazać wiele razy
--tag <tag>Wartość tagu; można przekazać wiele razy
--tags-json <path>Odczytuje tablicę tagów z pliku JSON
--tag-action <set|add|remove>Akcja wsadowa dla tagów

Przykładowa zawartość pliku --tags-json:

json
["cover", "2026", "public"]

Status czarnej i białej listy ​

Status listy określa zachowanie kontroli dostępu do pliku w trybie publicznego dostępu. Można zmienić go dla pojedynczego pliku albo wsadowo.

Ustawienie pojedynczego pliku na białą listę:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --set-list-type `
  --file-id "photos/2026/a.jpg" `
  --list-type White `
  --apply

Wsadowe dodanie plików do czarnej listy:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --batch-list-type `
  --file-id "photos/2026/a.jpg" `
  --file-id "photos/2026/b.jpg" `
  --list-type Block `
  --apply

Przywrócenie domyślnego statusu listy:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --set-list-type `
  --file-id "photos/2026/a.jpg" `
  --list-type None `
  --apply

Parametry czarnej i białej listy ​

ParametrOpis
--set-list-typeZmienia status listy jednego pliku
--batch-list-typeZmienia status listy plików wsadowo. Jedno żądanie obsługuje maksymalnie 15 plików
--file-id <id>ID pliku; w działaniach wsadowych można przekazać wiele razy
--list-type <None|White|Block>None to status domyślny, White to biała lista, a Block to czarna lista

Przenoszenie plików ​

Przenoszenie plików przenosi jeden lub więcej plików do katalogu docelowego. Backend przetwarza maksymalnie 15 plików w jednym żądaniu. Skrypt automatycznie dzieli pracę według --batch-size i wykonuje żądania po kolei.

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --move `
  --file-id "photos/2026/a.jpg" `
  --file-id "photos/2026/b.jpg" `
  --target-path "archive/2026" `
  --apply

Parametry przenoszenia ​

ParametrOpis
--movePrzenosi pliki
--file-id <id>ID pliku do przeniesienia; można przekazać wiele razy
--target-path <dir>Katalog docelowy
--batch-size <n>Liczba plików przenoszonych w jednym żądaniu; domyślnie 15, maksymalnie 15

Zmiana nazwy albo ścieżki ​

Zmiana nazwy używa jednoznacznego starego ID pliku i nowego ID pliku. Nowy ID pliku może zmieniać tylko nazwę pliku albo jednocześnie zmieniać katalog.

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --rename `
  --old-file-id "photos/2026/a.jpg" `
  --new-file-id "photos/2026/a-renamed.jpg" `
  --apply

Przy wsadowej zmianie nazwy powtarzaj --old-file-id i --new-file-id:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --rename `
  --old-file-id "photos/2026/a.jpg" `
  --new-file-id "archive/2026/a.jpg" `
  --old-file-id "photos/2026/b.jpg" `
  --new-file-id "archive/2026/b.jpg" `
  --apply

Mapowanie można też zapisać w pliku JSON:

json
[
  {
    "oldFileId": "photos/2026/a.jpg",
    "newFileId": "archive/2026/a.jpg"
  },
  {
    "oldFileId": "photos/2026/b.jpg",
    "newFileId": "archive/2026/b.jpg"
  }
]
powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --rename `
  --items-json ".\rename-items.json" `
  --apply

Parametry zmiany nazwy ​

ParametrOpis
--renameZmienia nazwę albo ścieżkę według jednoznacznego mapowania
--old-file-id <id>Oryginalny ID pliku; można przekazać wiele razy
--new-file-id <id>Nowy ID pliku; można przekazać wiele razy, a liczba musi odpowiadać --old-file-id
--items-json <path>Tablica JSON. Każdy element ma postać { "oldFileId": "...", "newFileId": "..." }
--batch-size <n>Liczba zmian nazwy przetwarzanych w jednym żądaniu; domyślnie 15, maksymalnie 15

Tworzenie folderów ​

Katalogi w ImgHost wynikają ze ścieżek plików; nie ma prawdziwych pustych katalogów. Gdy skrypt tworzy folder, tworzy w katalogu docelowym plik zastępczy 0.md, dzięki czemu folder jest widoczny w zarządzaniu plikami i statystykach katalogów.

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --create-folder `
  --parent-directory "photos" `
  --folder-name "2026" `
  --apply

Parametry tworzenia folderów ​

ParametrOpis
--create-folderTworzy plik zastępczy katalogu
--parent-directory <dir>Katalog nadrzędny; dla katalogu głównego przekaż pusty ciąg
--folder-name <name>Nazwa nowego folderu

Blokowanie i przywracanie IP przesyłania ​

Za pomocą uprawnienia do zarządzania można dodać IP do listy zablokowanych przesyłań albo usunąć je z tej listy. To działanie wpływa na przyszłe przesyłanie z tego IP, ale nie usuwa plików już przesłanych z tego adresu.

Zablokowanie IP przesyłania:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --block-ip "67.159.48.149" `
  --apply

Przywrócenie IP przesyłania:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --allow-ip "67.159.48.149" `
  --apply

Wyświetlenie bieżącej listy IP zablokowanych dla przesyłania:

powershell
node imghost-token-list.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --blocked-ips

Parametry zarządzania IP ​

ParametrOpis
--block-ip <ip>Dodaje IP do listy zablokowanych przesyłań
--allow-ip <ip>Usuwa IP z listy zablokowanych przesyłań

Tworzenie i usuwanie krótkoterminowych Tokenów przesyłania ​

Uprawnienie do zarządzania może tworzyć krótkoterminowe Tokeny przeznaczone wyłącznie do przesyłania. Taki Token zawsze ma tylko uprawnienie upload, autoDelete zawsze ma wartość true, a maksymalny czas wygaśnięcia wynosi 1 dzień.

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --create-upload-token `
  --name "Temporary Upload Token" `
  --owner "upload-bot" `
  --default-upload-channel telegram `
  --expires-in-minutes 20 `
  --apply `
  --output json

Możesz też przekazać bezpośrednio znacznik czasu w milisekundach:

powershell
$expiresAt = [DateTimeOffset]::UtcNow.AddHours(12).ToUnixTimeMilliseconds()

node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --create-upload-token `
  --name "Upload Token valid for one day" `
  --owner "upload-bot" `
  --default-upload-channel telegram `
  --expires-at $expiresAt `
  --apply

Podczas usuwania krótkoterminowego Tokenu przesyłania trzeba przekazać id zwrócony przez interfejs tworzenia. Token zarządzania może usuwać tylko Tokeny spełniające poniższe warunki:

WarunekWymaganie
Uprawnieniepermissions zawiera tylko upload
Automatyczne usuwanieautoDelete=true
Okres ważnościexpiresAt - createdAt <= 24 godziny

Usunięcie krótkoterminowego Tokenu przesyłania:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --delete-upload-token `
  --token-id "mqt4jqokc85be80d1f0f47078e848a77d6c1aa6e" `
  --apply

Token zarządzania nie może usuwać zwykłych Tokenów, Tokenów długoterminowych, Tokenów zawierających uprawnienia list / delete / manage ani Tokenów przesyłania ważnych dłużej niż 1 dzień. Takie Tokeny nadal trzeba obsługiwać w panelu administracyjnym w przeglądarce.

Parametry krótkoterminowego Tokenu przesyłania ​

ParametrOpis
--create-upload-tokenTworzy krótkoterminowy Token tylko do przesyłania
--delete-upload-tokenUsuwa kwalifikujący się krótkoterminowy Token tylko do przesyłania
--name <name>Nazwa Tokenu
--owner <owner>Opis właściciela Tokenu
--default-upload-channel <key>Domyślny kanał przesyłania. Musi być prawdziwym kanałem, np. telegram, s3 albo github
--expires-in-minutes <n>Liczba minut do wygaśnięcia od bieżącej chwili. Maksymalnie 1440
--expires-at <ms>Bezwzględny czas wygaśnięcia jako znacznik czasu w milisekundach. Maksymalnie 24 godziny od bieżącej chwili
--token-id <id>ID krótkoterminowego Tokenu przesyłania do usunięcia

Krótkoterminowe Tokeny przesyłania pozwalają tylko przesyłać pliki. W testach krótkoterminowy Token z permissions=["upload"] był odrzucany przy dostępie do interfejsów listowania, zarządzania plikami i usuwania.

Po wygaśnięciu Tokeny z autoDelete=true są czyszczone, gdy backend sprawdzi, że wygasły. Odczyt listy API Tokenów także czyści wygasłe Tokeny, których autoDelete ma wartość true.

Zestawienie interfejsów API ​

AkcjaMetodaAPI
Zmiana metadanych plikuPATCH/api/manage/metadata/{fileId}
Odczyt etykiety moderacjiGET/api/manage/label/{fileId}
Zmiana etykiety moderacjiPOST/api/manage/label/{fileId}
Odczyt tagów plikuGET/api/manage/tags/{fileId}
Zmiana tagów plikuPOST/api/manage/tags/{fileId}
Wsadowa zmiana tagów plikuPOST/api/manage/tags/batch
Zmiana statusu listyPOST/api/manage/listType/{fileId}
Wsadowa zmiana statusu listyPOST/api/manage/listType/batch
Przeniesienie albo zmiana nazwyPOST/api/manage/relocate/batch
Utworzenie folderuPOST/api/manage/folder/create
Zablokowanie IP przesyłaniaPOST/api/manage/cusConfig/blockip
Przywrócenie IP przesyłaniaPOST/api/manage/cusConfig/whiteip
Utworzenie krótkoterminowego Tokenu przesyłaniaPOST/api/manage/apiTokens
Usunięcie krótkoterminowego Tokenu przesyłaniaDELETE/api/manage/apiTokens?id={tokenId}

Skrypt automatycznie dodaje:

text
Authorization: Bearer your API Token

Format wyjścia ​

Domyślne wyjście pretty nadaje się do ręcznego odczytu. Jeśli wynik ma przetwarzać inny program, użyj --output json:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --get-tags `
  --file-id "photos/2026/a.jpg" `
  --output json

Możesz też zapisać pełny wynik:

powershell
node imghost-token-manage.mjs `
  --base-url "https://your-domain" `
  --token "your API Token" `
  --get-tags `
  --file-id "photos/2026/a.jpg" `
  --output json `
  --save-response ".\manage-result.json"

Wsadowe przenoszenie, wsadowa zmiana nazwy i wsadowe działania na listach analizują strumień postępu NDJSON zwracany przez backend oraz podsumowują liczbę zdarzeń, status ukończenia i szczegóły błędów.

Częste pytania ​

Dlaczego polecenie niczego nie zmieniło ​

Operacje zapisu domyślnie działają w trybie podglądu. Po potwierdzeniu, że podgląd jest poprawny, dodaj --apply, aby faktycznie zapisać zmianę.

Czy ten skrypt może przesyłać, listować albo usuwać pliki ​

Nie. Do przesyłania używaj skryptów przesyłania, do listowania i filtrowania używaj skryptu listowania, a do usuwania konkretnych plików używaj skryptu usuwania. Skrypt zarządzania plikami obsługuje tylko lekkie działania w ramach uprawnienia manage.

Skąd mam wiedzieć, który fileId przekazać ​

Najpierw wyszukaj pliki za pomocą imghost-token-list.mjs --files. Pole name w wyniku zwykle jest ID pliku, czyli wartością przekazywaną tutaj jako --file-id.

Ile plików może jednocześnie obsłużyć operacja wsadowa ​

Backend przetwarza maksymalnie 15 plików w jednym żądaniu. Skrypt domyślnie używa --batch-size 15; jeśli przekażesz mniejszą wartość, automatycznie podzieli pracę na kilka kolejnych żądań.

Czy można utworzyć naprawdę pusty folder ​

Katalogi ImgHost są wyprowadzane ze ścieżek plików, więc prawdziwe puste foldery nie istnieją. --create-folder tworzy plik zastępczy katalogu 0.md, dzięki czemu folder pojawia się w zarządzaniu plikami i statystykach katalogów.

Jak długo może działać krótkoterminowy Token przesyłania ​

Maksymalnie 1 dzień, czyli 1440 minut. Po przekroczeniu tego czasu skrypt odrzuci wartość lokalnie, a backend zwróci API_TOKEN_MANAGE_CREATE_EXPIRES_AT_TOO_LONG.

Czy krótkoterminowy Token przesyłania zostanie automatycznie usunięty po wygaśnięciu ​

Zostanie automatycznie wyczyszczony, ale nie przez natychmiastowe zadanie cykliczne. Wygasły Token jest czyszczony, gdy zostanie ponownie sprawdzony. Odczyt listy API Tokenów także czyści wygasłe Tokeny z autoDelete=true.

Released as user documentation for ImgHost.