Creative Lab — Keycap API

Zdjęcie źródłowe, które Meshy przekształci w obrazy projektu keycapa. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.

Format jest wykrywany poprzez dekodowanie danych obrazu, a nie na podstawie rozszerzenia pliku w adresie URL — adres URL bez rozszerzenia lub taki, który przekierowuje, zadziała, o ile bajty da się zdekodować do obsługiwanego formatu. Przekierowania HTTP są śledzone. Orientacja EXIF jest normalizowana, więc obrócone zdjęcie z telefonu jest używane w takiej postaci, w jakiej wygląda.

Ograniczenia: co najmniej 32 piksele po każdej stronie, co najwyżej 178 956 970 pikseli łącznie oraz co najwyżej 20 000 000 bajtów po pobraniu. W przypadku Data URI limit dotyczy bajtów po zdekodowaniu, więc sam plik źródłowy może mieć taki rozmiar — to tekst base64 jest o około jedną trzecią większy, co ma znaczenie dla treści żądania, ale nie dla tego limitu. Data URI musi deklarować typ zawartości image/* oraz ;base64.

Istnieją dwa sposoby dostarczenia obrazu:

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

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

Gdy ustawione na true, render wyświetlany zwrócony w image_urls jest przezroczystym plikiem PNG w formacie RGBA z usuniętym tłem, dzięki czemu możesz nałożyć go na dowolne tło.

Dotyczy to wyłącznie renderu wyświetlanego. Kandydat wykorzystywany przez punkt końcowy budowania nie jest tym objęty, więc wynik 3D jest identyczny w obu przypadkach.

Żądanie było niepoprawne. Typowe przyczyny:

• Brakujący parametr: image_url jest wymagany.
• Nieprawidłowy format obrazu: Podany image_url nie ma obsługiwanego formatu (.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.
• Oznaczona treść: Obraz wejściowy został oznaczony przez moderation NSFW.

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

Konto korzysta z planu darmowego (do tworzenia zadań wymagany jest płatny plan) lub ma niewystarczającą liczbę kredytów.

Obraz wejściowy został oznaczony przez moderation własności intelektualnej.

Przekroczono limit szybkości.

Wystąpił nieoczekiwany błąd po stronie serwera — na przykład usługa moderacji treści była niedostępna, przygotowanie obrazu wejściowego nie powiodło się, albo nie udało się utworzyć zadania. W takim przypadku żadne zadanie nie zostaje utworzone, więc ponowienie próby jest bezpieczne.

Identyfikator zadania prototypu utworzonego za pośrednictwem tego samego punktu końcowego OpenAPI. Prototyp musi zostać utworzony przez to samo konto Meshy, musi osiągnąć status SUCCEEDED i musi wygenerować co najmniej jednego kandydata.

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

Kandydat do zbudowania, pobrany z tablicy candidate_ids zakończonego powodzeniem zadania prototypu. Musi należeć do tego zadania; każda inna wartość zostanie odrzucona z kodem 400.

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

Podstawa klawisza, na której ma zostać zbudowany model. Obecnie jedyną dostępną wartością jest cherry-mx-1x1-r1 — standardowy klawisz o profilu Cherry MX 1u. Planowane jest 3–5 dodatkowych powszechnie stosowanych rozmiarów standardowych; niestandardowe rozmiary nie są obsługiwane.

Docelowy rozmiar rzeźbionej główki, w milimetrach: jej najdłuższy wymiar zostaje przeskalowany do tej wartości. Zakres: [10, 40]. Wartości powyżej około 32.9 mogą zostać zmniejszone, aby główka nadal mieściła się w limicie powierzchni ochronnej podstawy, więc dostarczony najdłuższy wymiar może być mniejszy niż żądany. Zastosowana wartość nie jest obecnie zwracana w obiekcie zadania — jeśli chcesz potwierdzić faktycznie otrzymany rozmiar, zmierz prostopadłościan ograniczający siatki keycap-head w pobranym modelu.

Przesunięcie pionowe stosowane do główki przed jej osadzeniem na podstawie, w milimetrach. Zakres: [-5, 5].

Żądanie było niepoprawne. Typowe przyczyny:

• Brakujący parametr: input_task_id i candidate_id są wymagane.
• Nieprawidłowy UUID: input_task_id nie jest prawidłowym identyfikatorem UUID.
• Zadanie nadrzędne nie zakończyło się powodzeniem: Zadanie prototypu, do którego się odwołano, nie osiągnęło jeszcze statusu SUCCEEDED.
• Brak kandydatów: Zadanie prototypu zakończyło się powodzeniem, ale nie wygenerowało żadnych kandydatów.
• Nieznany kandydat: candidate_id nie jest jednym z kandydatów zadania wejściowego.
• Opcje poza zakresem: Jedno z pól options znalazło się poza dozwolonym zakresem lub zbiorem wartości enum.

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

Konto korzysta z darmowego planu (do tworzenia zadań wymagany jest płatny plan) lub ma niewystarczającą liczbę kredytów.

Zadanie prototypu, do którego się odwołano, nie istnieje, należy do innego użytkownika lub zostało utworzone za pośrednictwem aplikacji webowej (tylko zadania prototypów w trybie API mogą być łączone w łańcuch z zadaniem budowy).

Przekroczono limit szybkości.

Wystąpił nieoczekiwany błąd po stronie serwera — na przykład usługa moderacji treści była niedostępna, nie udało się przygotować obrazu wejściowego lub nie można było utworzyć zadania. W takim przypadku żadne zadanie nie zostaje utworzone, więc ponowienie próby jest bezpieczne.

Unikalny identyfikator zadania keycap do pobrania.

Unikalny identyfikator zadania keycap do anulowania.

Zadanie jest już w stanie końcowym i nie można go anulować.

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

Podczas anulowania wystąpił nieoczekiwany błąd po stronie serwera. Zadanie mogło zostać anulowane lub nie — odczytaj je ponownie, aby to potwierdzić przed ponowną próbą.

Unikalny identyfikator zadania keycap do strumieniowania.

prototype albo build. Kolekcja zwraca tylko zadania, których etap odpowiada URL-owi — pobranie /prototype nigdy nie zwróci zadań budowania i odwrotnie.

Numer strony do stronicowania.

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

Pole, według którego dane są sortowane. 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. Chociaż jako szczegół implementacyjny używamy identyfikatorów zadań w postaci k-sortowalnych UUID, nie należy przyjmować żadnych założeń dotyczących formatu tego id.

Typ zadania. Wartość to creative-lab-keycap-prototype.

Nazwa zadania podana podczas jego tworzenia. Pusty ciąg znaków, jeśli nazwa nie została podana.

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

Postęp zadania (progress). Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość 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 nie zostało jeszcze rozpoczęte, ta właściwość wynosi 0.

Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie nie zostało jeszcze zakończone, ta właściwość wynosi 0.

Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach.

Liczba poprzedzających zadań.

Szczegóły błędu dla nieudanych zadań. Zobacz Błędy, aby poznać pełną strukturę 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 generuje obciążenia. Zadanie, które osiąga status FAILED, zwraca 0 — opłata jest zwracana, w tym w przypadku asynchronicznej blokady moderation. Anulowanie za pomocą DELETE powoduje zwrot środków tylko wtedy, gdy zadanie nadal ma status PENDING; zadanie, które jest już IN_PROGRESS, pozostaje obciążone, ponieważ praca została już wykonana.

Pobieralny URL renderu gotowego projektu nakładki klawisza — czyli tego, jak dany kandydat wygląda jako gotowa nakładka klawisza. Zawiera jeden wpis; image_urls[i] odpowiada candidate_ids[i]. Puste, dopóki zadanie nie osiągnie statusu SUCCEEDED. URL służy wyłącznie do wyświetlania; punkt końcowy budowy przyjmuje candidate_ids, a nie te adresy URL. Ten sam cykl życia URL co w przypadku model_urls: podpisany, bez nagłówka Authorization, ważny do momentu expires_at i stabilny przy ponownym odczycie zadania.

Nieprzezroczyste identyfikatory kandydatów, równoległe do image_urls. Przekaż wpis odpowiadający wybranemu przez Ciebie projektowi jako candidate_id żądania budowy. Nie należy przyjmować żadnych założeń dotyczących formatu tych identyfikatorów.

Unikalny identyfikator zadania.

Typ zadania. Wartość to creative-lab-keycap-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 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.

Znacznik czasu zakończenia zadania, w milisekundach.

Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach.

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

Szczegóły błędu dla nieudanych zadań. Zobacz Błędy, aby poznać pełny opis obiektu task_error.

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 (błąd 4xx w momencie żądania, w tym odrzucenie przez moderation) nie jest obciążane w ogóle. Zadanie, które osiągnie status FAILED, zwraca 0 — opłata jest zwracana, w tym w przypadku asynchronicznej blokady moderation. Anulowanie za pomocą DELETE zwraca opłatę tylko wtedy, gdy zadanie ma jeszcze status PENDING; zadanie już będące IN_PROGRESS pozostaje obciążone, ponieważ praca została już wykonana.

Adresy URL umożliwiające pobranie wygenerowanych plików modelu. Zarówno paczka GLB, jak i OBJ są eksportowane w rzeczywistej skali milimetrowej, w układzie Y-up, z przodem klawisza skierowanym w stronę +Z. Siatki nazwane są keycap-head i keycap-base; gdy podstawa korzysta z zapasowego wypełnienia wzorem, obecna jest również trzecia siatka keycap-base-interior dla wnęki trzpienia. Nie zakładaj, że zawsze będą dokładnie dwie siatki.

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 ponowny odczyt zadania w tym okresie zwraca dokładnie ten sam adres URL, a nie nowo podpisany. Pobierz i zapisz pliki samodzielnie przed tym terminem — nie ma możliwości odświeżenia wygasłego linku.

Adresy URL umożliwiające pobranie pośrednich obrazów procesu, indeksowane według rodzaju. Ten sam cykl życia adresu URL co w model_urls: podpisany, bez nagłówka Authorization, ważny do expires_at, i stabilny przy ponownym odczycie zadania. Obecnie generowane rodzaje:

• head_design — obraz projektu wybranego kandydata, wykorzystany przez budowę (zawsze obecny).
• composite — render prezentacyjny gotowego klawisza dla wybranego kandydata (obecny, gdy dostępny).
• base_canvas — pomalowane płótno podstawy klawisza (obecne, gdy dostępne).

Traktuj zbiór kluczy jako otwarty; nowe rodzaje mogą zostać dodane bez wprowadzania zmiany łamiącej kompatybilność.