Creative Lab — Fidget Pixel API

Zdjęcie źródłowe, które Meshy ma zamienić w piksele. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.

Format jest wykrywany poprzez dekodowanie danych obrazu, nie na podstawie rozszerzenia pliku w adresie URL — adres URL bez rozszerzenia lub taki, który przekierowuje, działa, o ile bajty dają się zdekodować do obsługiwanego formatu. Przekierowania HTTP są śledzone.

Istnieją dwa sposoby dostarczenia obrazu:

• Publicznie dostępny adres URL: Adres URL dostępny z publicznego internetu.
• Data URI: Zakodowany w base64 identyfikator Data URI obrazu. Przykład Data URI: data:image/jpeg;base64,<twoje zakodowane w base64 dane obrazu>.

Co przedstawia zdjęcie. Wybiera styl pikselizacji, więc wybieraj świadomie — te dwie opcje dają wyraźnie różne rezultaty. Dostępne wartości:

• person — obiektem jest osoba (portret lub cała sylwetka). Tworzy sprite'a w stylu chibi pixel-art przedstawiającego dany podmiot.
• other — cokolwiek innego: zwierzęta domowe, przedmioty, maskotki, logo, krajobrazy. Tworzy ikonę pikselową w stylu bead-art przedstawiającą dany podmiot.

Opcjonalna nazwa zadania do celów wyświetlania. Maksymalnie 100 znaków.

Żądanie było niepoprawne. Typowe przyczyny:

• Brakujący parametr: image_url i type są wymagane.
• Nieprawidłowy typ: type musi mieć wartość person lub other.
• Nieprawidłowy format obrazu: Podany image_url nie jest w obsługiwanym formacie (.jpg, .jpeg, .png, .webp).
• Wymiary obrazu poza zakresem: Obraz jest zbyt mały, przekracza maksymalny rozmiar pliku lub przekracza maksymalną liczbę pikseli.
• Nieosiągalny adres URL: Nie udało się pobrać image_url (404 lub timeout).
• Nieprawidłowy Data URI: Ciąg base64 jest nieprawidłowo sformatowany.
• Treść oznaczona: Obraz wejściowy został oznaczony przez moderation NSFW.

Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.

Niewystarczająca liczba kredytów do wykonania tego zadania lub klucz API należy do konta na darmowym planie.

Obraz wejściowy został oznaczony przez moderation własności intelektualnej (Content flagged for intellectual property violation). Blokowane są wyłącznie konta Enterprise z włączonym filtrowaniem własności intelektualnej; nic nie jest naliczane.

Przekroczono limit szybkości.

Nie udało się przeprowadzić samej kontroli własności intelektualnej (Unable to perform intellectual property check, please try again). Konta Enterprise z włączonym filtrowaniem własności intelektualnej zawodzą w trybie zamkniętym przy tej kontroli; nic nie jest naliczane — ponów żądanie.

Identyfikator zadania prototypu utworzonego za pomocą tego samego punktu końcowego OpenAPI. Prototyp musi zostać utworzony przez to samo konto Meshy i musi osiągnąć status SUCCEEDED.

Zadania prototypów utworzone za pośrednictwem aplikacji webowej nie są akceptowane — punkt końcowy budowania akceptuje wyłącznie zadania prototypów wygenerowane przez POST /openapi/creative-lab/fidget-pixel/v1/prototype i odrzuca każde inne źródło, zwracając 404.

Opcjonalna nazwa zadania do celów wyświetlania. Maksymalnie 100 znaków.

Kształt podstawy każdego elementu. Dostępne wartości:

• square (domyślnie) — kwadratowe elementy na kwadratowej siatce.
• hex — sześciokątne elementy na sześciokątnej siatce. Elementy heksagonalne są dostępne wyłącznie w rozmiarach 6 i 8 mm.

Liczba elementów wzdłuż każdego boku planszy. Dostępne wartości: 16 lub 32. Siatka 32 zachowuje więcej szczegółów; siatka 16 oznacza mniej, ale większe elementy dla tego samego motywu.

Długość krawędzi każdego elementu, w milimetrach. Dostępne wartości: 6, 8 lub 10. W połączeniu z grid_size ustala to rozmiar wydrukowanej planszy — na przykład 32 × 8 mm ≈ 26 cm na bok. Wartość 10 nie jest dostępna dla shape: "hex" (nachylona ścianka heksagonalna powoduje nawisy na większości konsumenckich drukarek FDM).

Maksymalna liczba kolorów w palecie, do której kwantyzowany jest obraz. Zakres: [1, 8]. Każdy kolor staje się jednym filamentem w Twoim slicerze.

Wysokość każdego elementu, w milimetrach. Zakres: [10, 80].

Artefakt zwracany przez proces budowania. Dostępne wartości:

• 3mf (domyślnie) — zwraca pojedynczy plik model.3mf pod adresem model_urls.3mf, z jednym obiektem na element i kolorem elementu przypisanym do każdego obiektu.

Żądanie było nieprawidłowe. Typowe przyczyny:

• Brakujący parametr: input_task_id jest wymagane.
• Nieprawidłowy UUID: input_task_id nie jest prawidłowym identyfikatorem UUID.
• Zadanie nadrzędne nie zakończyło się powodzeniem: Wskazane zadanie prototypu nie osiągnęło jeszcze statusu SUCCEEDED.
• Brak kandydata: Zadanie prototypu zakończyło się powodzeniem, ale nie wygenerowało obrazu pixel-art; utwórz nowy prototyp.
• Opcje poza zakresem: Jedno z pól options znajduje się poza dozwolonym zbiorem lub zakresem — na przykład options.grid_size must be 16 or 32 lub options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm.
• Nieobsługiwany format: output.format musi mieć wartość 3mf.

Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.

Niewystarczająca liczba kredytów do wykonania tego zadania lub klucz API należy do konta na planie darmowym.

Obraz wskazanego prototypu został oznaczony przez moderation własności intelektualnej. Blokowane są wyłącznie konta Enterprise z włączonym filtrowaniem własności intelektualnej; nic nie zostaje naliczone.

Wskazane zadanie prototypu nie istnieje, należy do innego użytkownika lub zostało utworzone za pośrednictwem aplikacji webowej (tylko zadania prototypów utworzone w trybie API mogą być łączone w łańcuch z budowaniem).

Przekroczono limit szybkości.

Nie udało się ustalić werdyktu dotyczącego własności intelektualnej dla wskazanego prototypu (Unable to perform intellectual property check, please try again). Konta Enterprise z włączonym filtrowaniem własności intelektualnej traktują taką sytuację jako niepowodzenie tego sprawdzenia; nic nie zostaje naliczone — spróbuj ponowić żądanie.

Unikalny identyfikator zadania fidget pixel do pobrania.

id nie jest prawidłowym UUID (Invalid ID).

Obraz zadania został oznaczony przez moderację własności intelektualnej. Blokowane są tylko konta Enterprise z włączonym filtrowaniem własności intelektualnej.

Zadanie nie istnieje, należy do innego użytkownika lub jego etap nie odpowiada ścieżce URL.

Nie udało się przeprowadzić weryfikacji własności intelektualnej (Unable to perform intellectual property check, please try again); konta Enterprise z włączonym filtrowaniem własności intelektualnej stosują zasadę „fail closed”. Ponów żądanie.

Unikalny identyfikator zadania fidget pixel do anulowania.

Żądanie było nieprawidłowe. Typowe przyczyny:

• Nieprawidłowe ID: id nie jest prawidłowym identyfikatorem UUID.
• Stan końcowy: Zadanie ma już status SUCCEEDED, FAILED lub CANCELED i nie może zostać anulowane.

Zadanie nie istnieje, należy do innego użytkownika lub jego etap nie odpowiada ścieżce URL.

Unikalny identyfikator zadania fidget pixel do strumieniowania.

Wartość prototype lub build. Kolekcja zwraca tylko zadania, których etap odpowiada adresowi URL — pobranie /prototype nigdy nie zwraca zadań budowy i odwrotnie.

Numer strony do stronicowania.

Limit rozmiaru strony. Maksymalna dozwolona wartość to 100 elementów.

Pole do sortowania. Dostępne wartości:

• +created_at: Sortuj według czasu utworzenia rosnąco.
• -created_at: Sortuj według czasu utworzenia malejąco.

Unikalny identyfikator zadania. Choć jako szczegół implementacyjny używamy dla identyfikatorów zadań UUID z możliwością sortowania k-sortable, nie należy zakładać niczego co do formatu tego identyfikatora.

Typ zadania. Wartość to creative-lab-fidget-pixel-prototype.

Nazwa zadania podana podczas jego tworzenia. Pusty ciąg znaków, jeśli nie podano nazwy.

Status zadania. Możliwe wartości to jedna z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Postęp zadania (progress). Jeśli zadanie jeszcze się nie rozpoczęło, ta wartość wynosi 0. Gdy zadanie zakończy się powodzeniem, wartość ta zmieni się na 100.

Znacznik czasu utworzenia zadania, w milisekundach.

Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie jeszcze się nie rozpoczęło, ta wartość to null.

Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie jeszcze się nie zakończyło, ta wartość to null.

Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach — 3 dni po zakończeniu zadania. Konta enterprise przechowują wyniki API bezterminowo (zobacz Przechowywanie zasobów); dla nich ten znacznik czasu jest ustawiony na około 100 lat naprzód.

Liczba poprzedzających zadań.

Szczegóły błędu dla nieudanych zadań. Pełny opis obiektu task_error znajdziesz w sekcji Błędy.

Liczba kredytów zużytych przez to zadanie. Zadanie, które osiągnie status SUCCEEDED, jest obciążane pełną kwotą za swój etap. Zadanie, które nigdy nie zostało utworzone (4xx w momencie żądania, w tym odrzucenie przez moderation), w ogóle nie jest obciążane. Zadanie, które zakończy się statusem FAILED, zwraca 0 — opłata jest zwracana. Anulowanie za pomocą DELETE powoduje zwrot środków tylko wtedy, gdy zadanie wciąż ma status PENDING; zadanie, które jest już IN_PROGRESS, pozostaje obciążone, ponieważ praca została już wykonana.

Adresy URL umożliwiające pobranie obrazu pixel-art wygenerowanego przez to zadanie prototypu. Obecnie API zawsze zwraca dokładnie jeden obraz; pole jest tablicą, aby przyszłe wersje mogły udostępniać wiele kandydatów bez wprowadzania zmian niekompatybilnych wstecz. Puste, dopóki zadanie nie osiągnie statusu SUCCEEDED.

Są to podpisane adresy URL: pobieraj je bez nagłówka Authorization. Pozostają ważne do momentu expires_at, czyli 3 dni po finished_at, a ponowne odczytanie zadania w tym okresie zwraca identyczny adres URL, a nie nowo podpisany. Pobierz i zapisz pliki samodzielnie przed upływem tego terminu — nie ma możliwości odświeżenia wygasłego linku.

Unikalny identyfikator zadania.

Typ zadania. Wartość to creative-lab-fidget-pixel-build.

Nazwa zadania podana podczas jego tworzenia. Pusty ciąg znaków, jeśli nie podano nazwy.

Status zadania. Możliwe wartości to jedna z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Postęp zadania. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie miała wartość 0. Gdy zadanie zakończy się powodzeniem, wartość ta zmieni się na 100.

Znacznik czasu utworzenia zadania, w milisekundach.

Znacznik czasu rozpoczęcia zadania, w milisekundach. null dopóki zadanie się nie rozpocznie.

Znacznik czasu zakończenia zadania, w milisekundach. null dopóki zadanie się nie zakończy.

Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach — 3 dni po zakończeniu zadania. Konta Enterprise przechowują wyniki API bezterminowo (zobacz Przechowywanie zasobów); dla nich ten znacznik czasu jest ustawiony na około 100 lat w przyszłość.

Liczba zadań poprzedzających. Ma znaczenie tylko wtedy, gdy status to PENDING.

Szczegóły błędu dla zadań zakończonych niepowodzeniem. Zobacz Błędy, aby poznać pełną specyfikację obiektu task_error.

Liczba kredytów zużytych przez to zadanie. Zadanie, które osiąga status SUCCEEDED, jest obciążane pełną kwotą za swój etap. Zadanie, które nigdy nie zostało utworzone (błąd 4xx w momencie żądania, w tym odrzucenie przez moderation) w ogóle nie jest obciążane. Zadanie, które osiąga status FAILED, zwraca 0 — opłata jest zwracana. Anulowanie za pomocą DELETE zwraca opłatę tylko wtedy, gdy zadanie nadal ma status PENDING; zadanie już w stanie IN_PROGRESS pozostaje obciążone, ponieważ praca została już wykonana.

Adresy URL do pobrania wygenerowanego artefaktu, kluczowane według formatu. Zawiera dokładnie jeden wpis — format żądany za pomocą pola output.format żądania budowy. Puste, dopóki zadanie nie osiągnie statusu SUCCEEDED.

Są to podpisane adresy URL: pobieraj je bez nagłówka Authorization. Pozostają ważne do momentu expires_at, czyli 3 dni po finished_at, a ponowne odczytanie zadania w tym okresie zwraca identyczny adres URL zamiast nowo podpisanego. Pobierz i zapisz pliki samodzielnie przed tym terminem — nie ma sposobu na odświeżenie wygasłego linku.