Creative Lab — Keycap API

Oryginalne zdjęcie, które Meshy przekształci w obrazy projektu keycapu. Obecnie obsługujemy formaty .jpg, .jpeg, .png i .webp.

Format jest wykrywany przez dekodowanie danych obrazu, nie na podstawie rozszerzenia pliku URL — URL bez rozszerzenia lub taki, który przekierowuje, działa, o ile bajty dekodują się do obsługiwanego formatu. Przekierowania HTTP są śledzone. Orientacja EXIF jest normalizowana, więc obrócone zdjęcie z telefonu jest używane tak, jak wygląda.

Limity: co najmniej 32 piksele z każdej strony, maksymalnie 178,956,970 pikseli w sumie i maksymalnie 20,000,000 bajtów po pobraniu. Dla Data URI limit dotyczy zdekodowanych bajtów, więc sam plik źródłowy może mieć do tej wielkości — jest to tekst base64, który jest około jednej trzeciej większy, co ma znaczenie dla treści żądania, a nie dla tego limitu. Data URI musi deklarować typ zawartości image/* i ;base64.

Istnieją dwa sposoby dostarczenia obrazu:

• Publicznie dostępny URL: URL, który jest dostępny z publicznego internetu.
• Data URI: zakodowany w base64 Data URI obrazu. Przykład Data URI: data:image/jpeg;base64,<twoje dane obrazu zakodowane w base64>.

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

Gdy ustawione na true, render wyświetlania zwrócony w image_urls jest przezroczystym RGBA PNG z usuniętym tłem, dzięki czemu można go skomponować na dowolnym tle.

Dotyczy to tylko renderu wyświetlania. Kandydat konsumowany przez punkt końcowy budowy pozostaje niezmieniony, więc wynik 3D jest identyczny w obu przypadkach.

Żądanie było nieakceptowalne. Typowe przyczyny:

• Brakujący parametr: image_url jest wymagany.
• Nieprawidłowy format obrazu: Podany image_url nie jest obsługiwanym formatem (.jpg, .jpeg, .png, .webp).
• Wymiary obrazu poza zakresem: Obraz jest zbyt mały, przekracza maksymalny rozmiar pliku lub przekracza maksymalną liczbę pikseli.
• Nieosiągalny URL: image_url nie mógł zostać pobrany (404 lub timeout).
• Nieprawidłowy Data URI: Ciąg base64 jest niepoprawny.
• Treść oznaczona: Obraz wejściowy został oznaczony przez moderation NSFW.

Uwierzytelnianie nie powiodło się. Proszę sprawdzić swój klucz API.

Konto jest na darmowym planie (wymagany jest płatny plan do tworzenia zadań) lub nie ma wystarczających kredytów.

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

Przekroczyłeś swój limit szybkości.

Wystąpił nieoczekiwany błąd po stronie serwera — na przykład usługa moderation treści była niedostępna, przygotowanie obrazu wejściowego nie powiodło się lub zadanie nie mogło zostać utworzone. W takim przypadku nie jest tworzone żadne zadanie, więc ponowne próby są bezpieczne.

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

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

Kandydat do budowy, wybrany z tablicy candidate_ids zakończonego sukcesem zadania prototypowego. Musi należeć do tego zadania; każda inna wartość jest odrzucana z 400.

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

Podstawa nakładki, na której ma być zbudowana. Obecnie jedyną dostępną wartością jest cherry-mx-1x1-r1 — standardowy profil nakładki Cherry MX 1u. Planowane są 3–5 dodatkowych standardowych rozmiarów; niestandardowe rozmiary nie są obsługiwane.

Docelowy rozmiar rzeźbionej głowy, w milimetrach: jej najdłuższy wymiar jest skalowany do tej wartości. Zakres: [10, 40]. Wartości powyżej około 32.9 mogą zostać zmniejszone, aby głowa nadal mieściła się w ograniczeniu ochronnej powierzchni 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 potrzebujesz potwierdzić otrzymany rozmiar, zmierz prostopadłościan ograniczający siatki keycap-head w pobranym modelu.

Pionowe przesunięcie zastosowane do głowy przed jej osadzeniem na podstawie, w milimetrach. Zakres: [-5, 5].

Żądanie było nieakceptowalne. Typowe przyczyny:

• Brakujący parametr: input_task_id i candidate_id są wymagane.
• Nieprawidłowy UUID: input_task_id nie jest prawidłowym UUID.
• Rodzic nie zakończony sukcesem: Odwołane zadanie prototypowe nie osiągnęło jeszcze SUCCEEDED.
• Brak kandydatów: Zadanie prototypowe zakończyło się sukcesem, 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 wykraczało poza dozwolony zakres lub zestaw enum.

Uwierzytelnianie nie powiodło się. Proszę sprawdzić swój klucz API.

Konto jest na darmowym planie (wymagany jest płatny plan do tworzenia zadań) lub ma niewystarczającą ilość kredytów.

Odwołane zadanie prototypowe nie istnieje, należy do innego użytkownika lub zostało utworzone za pośrednictwem aplikacji webowej (tylko zadania prototypowe w trybie API łączą się w budowę).

Przekroczyłeś swój 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 nie jest tworzone żadne zadanie, więc ponowienie jest bezpieczne.

Unikalny identyfikator zadania keycap do pobrania.

Unikalny identyfikator zadania keycap do anulowania.

Zadanie jest już w stanie końcowym i nie może być anulowane.

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

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

Unikalny identyfikator dla zadania keycap do transmisji.

Albo prototype, albo build. Kolekcja zwraca tylko zadania, których etap odpowiada ścieżce URL — pobieranie /prototype nigdy nie zwraca zadań budowlanych i odwrotnie.

Numer strony dla stronicowania.

Limit rozmiaru strony. Maksymalnie dozwolone to 100 elementów.

Pole do sortowania. Dostępne wartości:

• +created_at: Sortuj według czasu utworzenia w porządku rosnącym.
• -created_at: Sortuj według czasu utworzenia w porządku malejącym.

Unikalny identyfikator zadania. Chociaż używamy k-sortowalnego UUID dla identyfikatorów zadań jako szczegółu implementacji, nie powinieneś zakładać żadnych założeń dotyczących formatu tego identyfikatora.

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

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

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

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

Znacznik czasu utworzenia zadania, w milisekundach.

Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0.

Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie jeszcze się nie zakończyło, ta właściwość będzie miała wartość 0.

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

Liczba poprzedzających zadań.

Szczegóły błędu dla nieudanych zadań. Zobacz Błędy dla pełnej referencji obiektu task_error.

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

Pobieralny URL renderu projektu klawisza — jak wygląda kandydat jako gotowy klawisz. Zawiera jeden wpis; image_urls[i] odpowiada candidate_ids[i]. Pusty, dopóki zadanie nie osiągnie SUCCEEDED. URL jest tylko do wyświetlania; punkt końcowy budowy zużywa candidate_ids, a nie te URL-e. Ten sam cykl życia URL jak model_urls: podpisany, bez nagłówka Authorization, ważny do expires_at i stabilny, gdy zadanie jest ponownie odczytywane.

Nieprzejrzyste identyfikatory kandydatów, równoległe do image_urls. Przekaż wpis odpowiadający wybranemu projektowi jako candidate_id w żądaniu budowy. Nie zakładaj ż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 tworzenia zadania. Pusty ciąg znaków, jeśli nie podano nazwy.

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

Postęp zadania. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0. Po zakończeniu zadania sukcesem, wartość ta wyniesie 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ń. Znaczące tylko, gdy status to PENDING.

Szczegóły błędu dla nieudanych zadań. Zobacz Błędy dla pełnej referencji obiektu task_error.

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

Pobieralne URL-e dla wygenerowanych artefaktów modelu. Zarówno pakiet GLB, jak i OBJ są eksportowane w rzeczywistej skali milimetrowej, Y-up, z przodem keycapu skierowanym na +Z. Siatki są nazwane keycap-head i keycap-base; gdy podstawa wraca do wypełnienia wzorem, obecna jest również trzecia siatka keycap-base-interior dla wnęki trzonu. Nie zakładaj dokładnie dwóch siatek.

Są to podpisane URL-e: pobieraj je bez nagłówka Authorization. Pozostają ważne do expires_at, co jest 3 dni po finished_at, a ponowne odczytanie zadania w tym oknie zwraca identyczny URL zamiast nowo podpisanego. Pobierz i przechowaj pliki samodzielnie przed tym czasem — nie ma możliwości odświeżenia wygasłego linku.

Pobieralne URL-e dla pośrednich obrazów procesu, kluczowane według rodzaju. Taki sam cykl życia URL-i jak model_urls: podpisane, bez nagłówka Authorization, ważne do expires_at, i stabilne przy ponownym odczycie zadania. Obecnie emitowane rodzaje:

• head_design — obraz projektu wybranego kandydata, który budowa zużyła (zawsze obecny).
• composite — render wyświetlacza zakończonego keycapu wybranego kandydata (obecny, gdy dostępny).
• base_canvas — pomalowane płótno podstawy keycapu (obecne, gdy dostępne).

Traktuj zestaw kluczy jako otwarty; nowe rodzaje mogą być dodawane bez zmiany łamiącej.