Convert API

Convert API umożliwia konwersję istniejących modeli 3D do różnych formatów plików.

POST/openapi/v1/convert

Utwórz zadanie konwersji

Ten punkt końcowy tworzy nowe zadanie konwersji formatu.

Parametry

Wymagane jest podanie tylko jednego z input_task_id lub model_url. Jeśli podane zostaną oba, priorytet ma input_task_id.

  • Name
    input_task_id
    Type
    string
    Wymagane
    Description

    ID zakończonego zadania Meshy, którego model chcesz przekonwertować. Zadanie musi mieć status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Wymagane
    Description

    Publicznie dostępny adres URL lub Data URI wskazujące na plik modelu 3D. Wspierane formaty: .glb, .gltf, .obj, .fbx, .stl. W przypadku Data URI użyj MIME type: application/octet-stream.

  • Name
    target_formats
    Type
    string[]
    Wymagane
    Description

    Lista formatów wyjściowych dla przekonwertowanego modelu. Dostępne wartości: glb, fbx, obj, usdz, blend, stl, 3mf.

Wartość zwracana

Właściwość result odpowiedzi zawiera id nowo utworzonego zadania konwersji.

Tryby błędów

  • 400 - Bad Request

Żądanie było niepoprawne. Typowe przyczyny:

  • Brakujący parametr: Należy podać model_url lub input_task_id.
  • Brak target_formats: Należy podać przynajmniej jeden format docelowy.
  • Nieprawidłowe zadanie wejściowe: input_task_id musi wskazywać na zadanie zakończone sukcesem.
  • Nieprawidłowy format modelu: model_url wskazuje na plik z nieobsługiwanym rozszerzeniem.
  • Niedostępny adres URL: Nie udało się pobrać pliku z model_url.
  • 401 - Unauthorized

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

  • 402 - Payment Required

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

  • 429 - Too Many Requests

Przekroczono limit szybkości.

Request

POST
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

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

Pobierz zadanie konwersji

Ten punkt końcowy pobiera zadanie konwersji na podstawie jego ID.

Parametry

  • Name
    id
    Type
    path
    Description

    ID zadania konwersji do pobrania.

Zwraca

Obiekt zadania konwersji.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
DELETE/openapi/v1/convert/:id

Usuń zadanie konwersji

Ten punkt końcowy trwale usuwa zadanie konwersji, w tym wszystkie powiązane modele i dane. Ta operacja jest nieodwracalna.

Parametry ścieżki

  • Name
    id
    Type
    path
    Description

    Identyfikator zadania konwersji do usunięcia.

Status zadania

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

Zadanie, które ma już status IN_PROGRESS, nie może zostać usunięte: żądanie jest odrzucane z kodem 409 Conflict, a zadanie nadal jest wykonywane. Kredyty za zadanie, które proces roboczy już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania oznaczałoby utratę zarówno kredytów, jak i wyniku. 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.

Zwracane wartości

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

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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/convert

Lista zadań konwersji

Ten punkt końcowy umożliwia pobranie listy zadań konwersji.

Parametry

  • 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
    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.

Zwracane wartości

Zwraca stronicowaną listę Obiektów zadań konwersji.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]
GET/openapi/v1/convert/:id/stream

Strumieniowanie zadania konwersji

Ten punkt końcowy strumieniuje aktualizacje zadania konwersji w czasie rzeczywistym za pomocą Server-Sent Events (SSE).

Parametry

  • Name
    id
    Type
    path
    Description

    Unikalny identyfikator zadania konwersji do strumieniowania.

Zwraca

Zwraca strumień obiektów zadania konwersji jako Server-Sent Events.

Dla zadań o statusie PENDING lub IN_PROGRESS strumień odpowiedzi będzie zawierał tylko niezbędne pola progress i status.

Request

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

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Obiekt Convert Task

Obiekt Convert Task reprezentuje zadanie konwersji formatu.

Właściwości

  • id · string

Unikalny identyfikator zadania.

  • type · string

Typ zadania. Wartość to convert.

  • model_urls · object

Adresy URL do pobrania przekonwertowanych plików modelu. Adresy URL będą dostępne tylko dla formatów określonych w target_formats. Pozostałe właściwości formatów będą pustymi ciągami znaków.

  • progress · integer

Postęp zadania (0-100).

  • status · string

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

  • preceding_tasks · integer

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

  • created_at · znacznik czasu

Znacznik czasu utworzenia zadania, w milisekundach.

  • started_at · znacznik czasu

Znacznik czasu rozpoczęcia zadania, w milisekundach. 0, jeśli zadanie nie zostało rozpoczęte.

  • finished_at · znacznik czasu

Znacznik czasu zakończenia zadania, w milisekundach. 0, jeśli zadanie nie zostało zakończone.

  • task_error · object

Obiekt błędu, jeśli zadanie zakończyło się niepowodzeniem. Więcej informacji znajdziesz w sekcji Błędy.

  • consumed_credits · integer

Liczba kredytów zużytych przez to zadanie (1 kredyt za zadanie konwersji). Dla zadań ze statusem FAILED zwraca 0.