API druku wielokolorowego

Konwertuj modele 3D do wielokolorowego formatu 3MF do druku 3D, z konfigurowalną paletą kolorów obejmującą do 16 kolorów.

POST/openapi/v1/print/multi-color

Utwórz zadanie druku 3D wielokolorowego

Ten punkt końcowy tworzy nowe zadanie druku 3D wielokolorowego. Zadanie konwertuje model 3D na wielokolorowy plik 3MF odpowiedni do druku 3D.

Parametry

Wymagany jest tylko jeden z parametrów input_task_id lub model_url. Jeśli podano oba, priorytet ma input_task_id.

  • Name
    model_url
    Type
    string
    Wymagane
    Description

    Publicznie dostępny URL lub Data URI modelu 3D. Obecnie obsługujemy formaty .glb i .fbx.

  • Name
    max_colors
    Type
    integer
    domyślne 4
    Description

    Maksymalna liczba kolorów w wynikowej palecie.

    Prawidłowy zakres: od 1 do 16.

  • Name
    style
    Type
    string
    domyślne realistic
    Description

    Wizualny styl kolorystyczny wygenerowanego pliku 3MF.

    Dostępne wartości:

    • realistic: Pobiera próbki kolorów bezpośrednio z tekstury modelu, uzyskując drobne, fotorealistyczne detale. Powoduje powstanie większego pliku.
    • cartoon: Spłaszcza kolory do czystych, jednolitych obszarów, uzyskując stylizowany wygląd. Powoduje powstanie mniejszego pliku.

    Dane wejściowe muszą zawierać informacje o kolorze: realistic wymaga pojedynczej podstawowej tekstury koloru ze współrzędnymi UV na każdej części siatki; cartoon akceptuje również kolory na wierzchołkach. Modele bez tekstury (białe) są odrzucane — zobacz model_missing_texture.

Zwracane dane

Właściwość result odpowiedzi zawiera id nowo utworzonego zadania druku 3D.

Tryby niepowodzenia

  • Name
    400 - Bad Request
    Description

    Żądanie było niepoprawne. Częste przyczyny:

    • Brakujący parametr: Należy podać model_url lub input_task_id.
    • Nieprawidłowy format modelu: model_url wskazuje na plik z nieobsługiwanym rozszerzeniem (obsługiwane są tylko .glb i .fbx).
    • Niedostępny URL: Nie udało się pobrać pliku spod model_url.
    • Nieprawidłowe zadanie wejściowe: input_task_id musi wskazywać na zadanie zakończone powodzeniem.
    • Nieprawidłowe max_colors: Wartość musi mieścić się w zakresie od 1 do 16.
    • Nieprawidłowy style: Wartość musi wynosić realistic lub cartoon.
    • Brak źródła koloru: Model wejściowy nie ma podstawowej tekstury koloru (realistic wymaga jednej, ze współrzędnymi UV, na każdej części siatki) ani kolorów wierzchołków (cartoon akceptuje jedno lub drugie). Najpierw nałóż teksturę na model lub użyj cartoon dla modeli z kolorami wierzchołków. Pliki .fbx są sprawdzane po tym, jak zadanie je znormalizuje, i kończą się niepowodzeniem z błędem model_missing_texture.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Niewystarczająca liczba kredytów do wykonania tego zadania.

  • Name
    429 - Too Many Requests
    Description

    Przekroczono limit szybkości.

Request

POST
/openapi/v1/print/multi-color
# Convert a 3D model to multi-color 3MF for printing
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/multi-color/:id

Pobierz zadanie druku 3D wielokolorowego

Ten punkt końcowy pobiera zadanie druku 3D wielokolorowego na podstawie jego ID.

Parametry

  • Name
    id
    Type
    path
    Description

    ID zadania druku 3D, które ma zostać pobrane.

Wartość zwracana

Obiekt zadania druku 3D.

Request

GET
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}
DELETE/openapi/v1/print/multi-color/:id

Usuwanie zadania druku 3D wielokolorowego

Ten punkt końcowy trwale usuwa zadanie druku 3D wielokolorowego, wraz ze wszystkimi powiązanymi modelami i danymi. Ta czynność jest nieodwracalna.

Parametry ścieżki

  • Name
    id
    Type
    path
    Description

    Identyfikator zadania druku 3D wielokolorowego, które ma zostać usunięte.

Status zadania

Zadanie, które nadal ma status PENDING, zostaje usunięte, a kredyty zużyte w momencie jego utworzenia są zwracane.

Zadania, które jest już w stanie IN_PROGRESS, nie można usunąć: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie nadal działa. Kredyty za zadanie, które worker już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie działania kosztowałoby zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) zostaje usunięte bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

Request

DELETE
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
GET/openapi/v1/print/multi-color

Lista zadań druku 3D wielokolorowego

Ten punkt końcowy umożliwia pobranie listy zadań druku 3D wielokolorowego.

Parametry

Atrybuty opcjonalne

  • Name
    page_num
    Type
    integer
    Description

    Numer strony na potrzeby stronicowania. Zaczyna się i domyślnie wynosi 1.

  • Name
    page_size
    Type
    integer
    Description

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

  • Name
    sort_by
    Type
    string
    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 druku 3D.

Request

GET
/openapi/v1/print/multi-color
curl https://api.meshy.ai/openapi/v1/print/multi-color?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]
GET/openapi/v1/print/multi-color/:id/stream

Strumieniowanie zadania druku 3D w wielu kolorach

Ten punkt końcowy strumieniuje aktualizacje w czasie rzeczywistym dla zadania druku 3D w wielu kolorach za pomocą Server-Sent Events (SSE).

Parametry

  • Name
    id
    Type
    path
    Description

    Unikalny identyfikator zadania druku 3D w wielu kolorach do strumieniowania.

Zwraca

Zwraca strumień obiektów zadania druku 3D jako Server-Sent Events.

W przypadku zadań PENDING lub IN_PROGRESS strumień odpowiedzi będzie zawierał wyłącznie niezbędne pola progress i status.

Request

GET
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
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": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Obiekt zadania druku 3D

  • Name
    id
    Type
    string
    Description

    Unikalny identyfikator zadania. Chociaż jako szczegół implementacyjny używamy identyfikatorów zadań w postaci k-sortowalnego UUID, nie należy przyjmować żadnych założeń co do formatu tego identyfikatora.

  • Name
    type
    Type
    string
    Description

    Typ zadania druku 3D. Wartość to print-multi-color.

  • Name
    model_urls
    Type
    object
    Description

    Adres URL do pobrania pliku modelu 3D wygenerowanego przez Meshy. Właściwość dla danego formatu zostanie pominięta, jeśli dany format nie został wygenerowany, zamiast zwracać pusty ciąg znaków.

    • Name
      3mf
      Type
      string
      Description

      Adres URL do pobrania wielokolorowego pliku 3MF.

  • Name
    progress
    Type
    integer
    Description

    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ę sukcesem, wartość ta zmieni się na 100.

  • Name
    status
    Type
    string
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Liczba poprzedzających zadań.

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

  • Name
    created_at
    Type
    timestamp
    Description

    Znacznik czasu utworzenia zadania, w milisekundach.

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • 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. Dla zadań FAILED zwraca 0 (kredyty są zwracane w przypadku niepowodzenia).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}