Skip to main content
POST
Wygeneruj obraz dla połączonego konta. Obowiązują te same limity multimediów i zabezpieczenia co w aplikacji internetowej. Zapisz zwrócony generationId i użyj images_download, aby pobrać obraz. Przy ponawianiu tego samego żądania używaj ponownie requestId.

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: images: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
Wartość tekstowa.Minimalna długość: 10. Maksymalna długość: 1200.
string
Wartość tekstowa.Dozwolone wartości: “square”, “landscape”, “portrait”. Wartość domyślna: “square”.
string
Klucz przesłanego obiektu JPG, PNG lub WebP w uploads/{yourUserId}/. Zdalne adresy URL nie są akceptowane.Minimalna długość: 1. Maksymalna długość: 512.
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ź

Ta operacja zwraca HTTP 202 podczas przetwarzania. Zapisz requestId i odpytuj action_request_get, podając ten identyfikator oraz nazwę pierwotnej operacji. Stany odpytywania to running, completed, failed i interrupted. Zakończony wynik może wskazywać osobne zadanie przetwarzania multimediów; kontynuuj za pomocą akcji stanu lub wyniku właściwej dla tej operacji. Końcowe metadane generowania zwracane przez procedurę obsługi po zakończeniu generowania obrazu. Nie zawierają bajtów obrazu, previewDataUrl ani adresu URL pobierania.

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 images:write. Z promptu usuwane są białe znaki z początku i końca, a jego długość musi wynosić 10–1200 znaków; przed generowaniem jest on również normalizowany. aspectRatio ma domyślnie wartość square i akceptuje również landscape lub portrait. Akceptowany jest co najwyżej jeden referenceImageKey.
  • To długotrwała akcja. Początkowa odpowiedź API/MCP zwykle wskazuje running; sprawdzaj stan przez action_request_get z operation o wartości images_generate i tym samym requestId, aby uzyskać pokazany tutaj wynik końcowy.
  • Korzysta ze standardowego dziennego limitu generowania obrazów dla konta. Obrazy wygenerowane na koncie wygasają siedem dni po utworzeniu; pobierz wynik przed expiresAt.
  • Ta akcja korzysta z własnych utworzonych materiałów i przesłanych plików połączonego użytkownika, również gdy dane uwierzytelniające są połączone w kontekście zespołu.
  • Klucze referencji muszą wskazywać ukończone przesłania w uploads/{yourUserId}/ i kończyć się na .jpg, .jpeg, .png lub .webp. Zdalne adresy URL, klucze innych użytkowników, segmenty przechodzenia po katalogach, ukośniki odwrotne, sekwencje kodowania procentowego, ciągi zapytania, fragmenty i znaki sterujące są odrzucane.
  • Każdy obraz referencyjny musi być niepusty, mieć rozmiar najwyżej 8 MiB (8,388,608 bajtów), dawać się zdekodować jako typ obrazu wskazany przez rozszerzenie i mieć 128–4096 pikseli na każdym boku. Liczba zdekodowanych pikseli również podlega ograniczeniom. Przesłany obraz referencyjny pozostaje dostępny do ponownego użycia; te akcje generowania nie zużywają ani nie usuwają jego przesłanego pliku.
  • 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.
  • Dla tego użytkownika można generować tylko jeden obraz naraz. Użyj images_list i images_get, aby sprawdzić stan tworzenia, oraz images_download, aby pobrać bajty PNG. Identyfikator generowania jest nieprzezroczystym ciągiem znaków; nie zastępuj go requestId.

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