Skip to main content
POST
Zakończ należące do Ciebie przesyłanie obrazu referencyjnego, używając numerów części i ETag z żądań PUT. Sprawdza rozmiar zapisanego pliku. Użyj zwróconego fileKey jako obrazu referencyjnego do generowania.

Uwierzytelnianie i uprawnienia

string
wymagane
Wyślij klucz API VoiceCheap w tym nagłówku. Obsługiwany jest również nagłówek Authorization: Bearer z tym samym kluczem API. Tokeny dostępu OAuth są akceptowane tylko przez MCP, a nie przez ten endpoint REST.
Wymagane uprawnienia: thumbnails:write. Wymagana jest aktywna płatna subskrypcja. Uprawnienia nie zmieniają ról w zespole, własności zasobów, kredytów na multimedia ani limitów planu.

Parametry

string
Opcjonalne na poziomie transportu: jeśli identyfikator zostanie pominięty, serwer doda go przed walidacją. Podaj własny, stały UUID v4, aby bezpiecznie odzyskać wynik po utracie odpowiedzi.Format: “uuid”. Wzorzec: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
string
wymagane
uploadId zwrócony przez akcję upload_initialize tej domeny.Format: “uuid”. Wzorzec: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$.
array
wymagane
Lista wartości. Strukturę elementów opisuje pełny schemat danych wejściowych.Minimalna liczba elementów: 1. Maksymalna liczba elementów: 2.
Poniższy JSON Schema zachowuje dokładne nazwy pól, typy zagnieżdżone, wartości domyślne, ograniczenia i akceptowane wartości udostępniane przez mechanizm wykrywania. Dodatkowe reguły zależności między polami znajdują się w uwagach do operacji.

Idempotencja

Dla każdej operacji zmieniającej dane użyj UUID v4 w requestId lub w nagłówku HTTP Idempotency-Key. Po awarii sieci użyj ponownie tego samego identyfikatora i identycznych argumentów. Jeśli podasz oba, muszą być zgodne. Ponowienie zapisanego żądania nie powtarza operacji ani nie zużywa kolejnego wywołania z miesięcznego limitu. Żądania zakończone błędem lub przerwane nie są automatycznie uruchamiane ponownie. Każda operacja zmieniająca dane może zwrócić HTTP 202, gdy ponowienie napotka to samo żądanie nadal w stanie running, nawet jeśli jej pierwsze wykonanie zwykle jest synchroniczne. Jeśli wykonanie się zakończyło, ale resultStored ma wartość false, ponowienie zwraca HTTP 200 z zapisanym stanem żądania zamiast pierwotnego wyniku. Pobierz wynik za pomocą akcji historii, wyniku lub pobierania właściwej dla danej domeny.

Przykłady żądań

Zastąp przykładowe identyfikatory zasobów i klucze multimediów wartościami zwróconymi dla Twojego konta. Przy ponawianiu tej samej operacji zmieniającej dane zachowaj identyfikator żądania.

Odpowiedź

Pierwsze pomyślne wykonanie zwraca HTTP 200 z wynikiem operacji w data. Ponowienie może zamiast tego zwrócić zapisany stan żądania. Przykład przedstawia jedną obsługiwaną odpowiedź, bez wszystkich opcjonalnych pól. Klucz ukończonego pliku referencyjnego należącego do użytkownika i jego adres URL do odczytu, zwracane dopiero wtedy, gdy liczba zapisanych bajtów dokładnie odpowiada zadeklarowanemu rozmiarowi pliku. W argumentach generowania używaj fileKey, a nie readUrl.

Pola wyniku

Odzyskaj żądanie i sprawdź jego stan

Używaj tego samego identyfikatora także po utracie połączenia. Jeśli resultStored ma wartość false, pobierz wynik za pomocą odpowiedniej akcji historii, wyniku lub pobierania. Nigdy nie uruchamiaj drugiego generowania tylko po to, aby sprawdzić postęp.
HTTP 200

Uwagi do operacji

  • Wymaga thumbnails:write; dodatkowy zakres przesyłania nie jest potrzebny.
  • uploadId to UUID z initialize. parts zawiera dokładnie 1–2 części wymagane przez sesję. Każda część ma całkowite partNumber od 1 do 2 i ciąg etag o długości 1–256 znaków pobrany z odpowiedzi udanego PUT.
  • Wszystkie numery części muszą być obecne i unikatowe. Przed ukończeniem części są sortowane, a wartości ETag są normalizowane do wartości w cudzysłowach. Możesz zachować cudzysłowy ETag zwrócone przez magazyn danych.
  • Rzeczywista długość ukończonego obiektu w bajtach jest porównywana z fileSize i limitem 8 MiB. Brak długości, jej niezgodność lub przekroczenie limitu powoduje usunięcie obiektu i aktywnej sesji oraz zwrócenie UPLOAD_SIZE_MISMATCH.
  • Przekaż fileKey jako element referenceImageKeys w thumbnails_generate. Ukończone pliki referencyjne mogą być ponownie używane przy kolejnych generowaniach obrazów lub miniatur należących do tego samego użytkownika; generowanie nie zużywa pliku referencyjnego.
  • Tylko przesłany plik należący do połączonego użytkownika może zostać podpisany, ukończony lub przerwany. Te aliasy akceptują tylko sesje JPG, PNG i WebP o rozmiarze maksymalnie 8 MiB, nawet jeśli sesja została utworzona przez inną rodzinę przesyłania.
  • Produkcyjna sesja przesyłania wygasa po 24 godzinach. Podpisane adresy URL części wygasają po jednej godzinie. Zakończenie i przerwanie przesyłania usuwa aktywną sesję; sign-parts i complete zwracają wtedy Upload not found. Żadna z tych odpowiedzi nie zawiera pola expiresAt.
  • Użyj requestId w formacie UUID v4 lub nagłówka HTTP Idempotency-Key i używaj tej samej wartości z identycznymi danymi wejściowymi przy ponownych próbach. Warstwa integracji zapisuje każdą modyfikację i zwraca jej zapisany stan lub wynik bez ponownego wykonywania. Żądanie w stanie failed lub interrupted nie jest automatycznie ponawiane.
  • Ukończenie zamyka sesję przesyłania wieloczęściowego. Ponów ukończenie z oryginalnym requestId, aby pobrać zapisany wynik; nowe żądanie ukończenia dla tego zamkniętego uploadId zwraca Upload not found. Ta akcja nie zwraca terminu wygaśnięcia przechowywanego pliku referencyjnego.

Wykorzystanie

Każde pomyślne wywołanie zużywa jedno wywołanie z miesięcznego limitu API/MCP. Obowiązują również kredyty na multimedia oraz limity generowania danej operacji.

Błędy