Creative Lab — API składanego fidgeta

Zamień zdjęcie źródłowe w gotową do druku, składaną zabawkę typu fidget: sylwetka obiektu staje się zestawem zagnieżdżonych współśrodkowych pierścieni, które składają się płasko i ponownie się rozciągają, wydrukowaną w jednym kawałku, bez konieczności montażu.

  • POST /openapi/creative-lab/fidget-collapsible/v1

W przeciwieństwie do pozostałych endpointów Creative Lab, ten nie ma pary etapów prototyp/kompilacja — nie ma pośrednich kandydatów, spośród których trzeba by wybierać, więc pojedyncze zadanie prowadzi obraz aż do modelu 3D. Elementy sterujące geometrią, udostępniane przez aplikację webową (rozmiar, liczba warstw, szerokość szczeliny, grubość ścianki, głębokość wytłoczenia, wybrzuszenie), również nie są częścią żądania: każde zadanie jest budowane z takimi samymi domyślnymi ustawieniami po stronie serwera.

POST/openapi/creative-lab/fidget-collapsible/v1

Utwórz zadanie Collapsible Fidget

Wygeneruj model składanego fidgeta (collapsible fidget) na podstawie zdjęcia źródłowego. Zapoznaj się z Obiektem zadania Collapsible Fidget, aby poznać kształt odpowiedzi.

Każde zadanie kosztuje 6 kredytów i wymaga płatnego planu.

Parametry

  • Name
    image_url
    Type
    string
    Wymagane
    Description

    Zdjęcie źródłowe, które Meshy ma przekształcić w składanego fidgeta. Obecnie obsługujemy formaty .jpg, .jpeg, .png oraz .webp.

    Istnieją dwa sposoby dostarczenia obrazu:

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

    Najlepiej sprawdza się obiekt o jednym wyraźnym, zamkniętym konturze — to sylwetka staje się pierścieniami. Ruchliwe tła, kilka oddzielnych obiektów lub bardzo cienkie kształty mogą pozostawić zbyt mało miejsca na zagnieżdżone ścianki, w wyniku czego zadanie kończy się błędem.

  • Name
    name
    Type
    string
    Description

    Opcjonalna nazwa zadania używana do celów wyświetlania. Maksymalnie 100 znaków. Jest to wyłącznie etykieta zadania; nic nie zostaje wygrawerowane na modelu.

Zwracane wartości

Właściwość result w odpowiedzi zawiera id zadania nowo utworzonego zadania collapsible fidget. Odpytuj punkt końcowy Pobierz zadanie lub subskrybuj strumień, aż zadanie osiągnie status SUCCEEDED, a następnie pobierz gotowy do druku plik STL z model_urls.stl (a jeśli jest dostępny, plik GLB z model_urls.glb, aby najpierw podejrzeć model).

Tryby awarii

  • Name
    400 - Bad Request
    Description

    Żądanie było nieprawidłowe. Najczęstsze przyczyny:

    • Brakujący parametr: image_url jest wymagany.
    • 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 URL: nie udało się pobrać image_url (404 lub timeout).
    • Nieprawidłowy Data URI: ciąg base64 jest nieprawidłowo sformułowany.
    • Oznaczona treść: obraz wejściowy został oznaczony przez moderation NSFW.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Albo Twoje konto korzysta z darmowego planu — utworzenie zadania w tym punkcie końcowym wymaga płatnego planu — albo masz niewystarczającą liczbę kredytów.

  • Name
    403 - Forbidden
    Description

    Obraz wejściowy został oznaczony za naruszenie praw własności intelektualnej.

  • Name
    429 - Too Many Requests
    Description

    Przekroczono limit szybkości.

Request

POST
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1 \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/creative-lab/fidget-collapsible/v1/:id

Pobierz zadanie składanego fidget spinnera

Pobierz zadanie składanego fidget spinnera na podstawie prawidłowego id zadania. Tylko zadania utworzone za pomocą tego punktu końcowego są tutaj dostępne — zadanie z innego punktu końcowego Creative Lab lub zadanie utworzone w aplikacji webowej zwraca 404.

Zapoznaj się z sekcją Obiekt zadania składanego fidget spinnera dla informacji o strukturze odpowiedzi.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikalny identyfikator zadania składanego fidget spinnera do pobrania.

Zwracane wartości

Odpowiedź zawiera obiekt zadania składanego fidget spinnera.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Usuń zadanie Collapsible Fidget

Anuluje zadanie collapsible fidget. Jeśli zadanie ma nadal status PENDING, kredyty zużyte w momencie utworzenia zostają zwrócone. Zadania, które są już w stanie IN_PROGRESS, są anulowane bez zwrotu (worker mógł już zużywać zasoby). Zadań, które osiągnęły już stan końcowy (SUCCEEDED, FAILED, CANCELED), nie można anulować.

Parametry ścieżki

  • Name
    id
    Type
    path
    Description

    Unikalny identyfikator zadania collapsible fidget do anulowania.

Zwraca

Zwraca 204 No Content w przypadku sukcesu, z pustą treścią.

Tryby błędów

  • Name
    400 - Bad Request
    Description

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

  • Name
    404 - Not Found
    Description

    Zadanie nie istnieje, należy do innego użytkownika lub nie zostało utworzone za pomocą tego punktu końcowego.

Request

DELETE
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).
GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Przesyłanie strumieniowe zadania składanego fidgetu

Przesyłaj strumieniowo aktualizacje w czasie rzeczywistym dla zadania składanego fidgetu za pomocą Server-Sent Events (SSE). Zadanie, które nie istnieje lub nie zostało utworzone za pomocą tego punktu końcowego, emituje pojedynczy ładunek event: error z status_code: 404 i zamyka strumień.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikalny identyfikator zadania składanego fidgetu do przesyłania strumieniowego.

Zwraca

Zwraca strumień obiektów zadań Collapsible Fidget w formie Server-Sent Events. W przypadku zadań o statusie PENDING lub IN_PROGRESS, strumień odpowiedzi będzie zawierał tylko niezbędne pola progress i status.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

Lista zadań składanego fidgeta

Pobierz stronicowaną listę Twoich zadań składanego fidgeta. Uwzględnione są tylko zadania utworzone za pomocą tego punktu końcowego.

Parametry zapytania

  • Name
    page_num
    Type
    integer
    domyślne 1
    Description

    Numer strony do stronicowania.

  • Name
    page_size
    Type
    integer
    domyślne 10
    Description

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

  • Name
    sort_by
    Type
    string
    domyślne -created_at
    Description

    Pole, według którego ma nastąpić sortowanie. Dostępne wartości:

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

Zwraca

Zwraca stronicowaną listę obiektów zadania składanego fidgeta.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.cn/openapi/creative-lab/fidget-collapsible/v1?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

The Collapsible Fidget Task Object

Obiekt Collapsible Fidget Task to jednostka pracy, którą Meshy śledzi w celu przekształcenia zdjęcia źródłowego w drukowany od razu w złożonej postaci model składanego fidgeta. Jest to zadanie jednoetapowe: nie ma prototypu, z którego można by kontynuować, a pośrednia sylwetka nie stanowi części odpowiedzi.

Właściwości

  • Name
    id
    Type
    string
    Description

    Unikalny identyfikator zadania. Chociaż jako szczegół implementacyjny używamy identyfikatorów zadań w formacie k-sortowalnego UUID, nie należy zakładać żadnego konkretnego formatu id.

  • Name
    type
    Type
    string
    Description

    Typ zadania. Wartość to creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    Postęp zadania. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość ma wartość 0. Gdy zadanie zakończy się powodzeniem, przyjmie wartość 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Znacznik czasu utworzenia zadania, w milisekundach.

    Znacznik czasu reprezentuje liczbę milisekund, które upłynęły od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład piątek, 1 września 2023, godzina 12:00:00 czasu GMT jest reprezentowany jako 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Liczba poprzedzających zadań.

    Wartość tego pola ma znaczenie tylko wtedy, gdy status zadania to PENDING.

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Liczba kredytów zużytych przez to zadanie. Obecne, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).

  • Name
    model_urls
    Type
    object
    Description

    Adresy URL do pobrania wygenerowanego modelu 3D. Wypełniane po tym, jak zadanie osiągnie status SUCCEEDED: stl jest zawsze obecny, glb tylko wtedy, gdy renderowanie podglądu się powiodło.

    • Name
      stl
      Type
      string
      Description

      Adres URL do pobrania pliku STL. To jest gotowy do druku plik wynikowy — wyślij go bezpośrednio do slicera.

    • Name
      glb
      Type
      string
      Description

      Adres URL do pobrania pliku GLB, umożliwiający podgląd modelu w przeglądarce 3D. Jego kolory służą wyłącznie do podglądu: STL nie zawiera informacji o kolorze, a wydrukowany fidget przyjmuje kolor filamentu. GLB jest generowany na zasadzie „najlepszego wysiłku”: gdy renderowanie podglądu jest niedostępne, klucz ten jest całkowicie pomijany w model_urls, dlatego należy go odczytywać z zabezpieczeniem — stl jest właściwym plikiem wynikowym i jest zawsze obecny w zadaniu ze statusem SUCCEEDED.

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}