Zmień rozmiar API

Zmień rozmiar API umożliwia zmianę rozmiaru istniejących modeli 3D do rzeczywistych wymiarów. Możesz określić dokładną wysokość, ograniczenie najdłuższego boku, lub pozwolić sztucznej inteligencji automatycznie oszacować odpowiedni rozmiar.

POST/openapi/v1/resize

Create a Resize Task

Ten punkt końcowy tworzy nowe zadanie zmiany rozmiaru.

Zadanie jest wykonywane w tle. Informacje o typowym czasie trwania znajdziesz w Czasach przetwarzania.

Parametry

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

Name
input_task_id
Type
string
Wymagane
Description
ID ukończonego zadania Meshy, którego model chcesz zmienić rozmiar. Zadanie musi mieć status SUCCEEDED. Format wyjściowy będzie GLB.

Name
model_url
Type
string
Wymagane
Description
Publicznie dostępny URL lub identyfikator URI danych wskazujący na plik modelu 3D. Obsługiwane formaty: .glb, .gltf, .obj, .fbx, .stl. W przypadku Data URI użyj typu MIME: application/octet-stream. URL .glb, .obj, .fbx lub .stl zachowuje swój format na wyjściu; URL .gltf lub data URI generuje GLB.
Maksymalny rozmiar pliku: 400 MB dla URL http lub https, 100 MB dla URI data:.
Plik GLB, glTF, FBX lub OBJ przekraczający 100 MB może mieć maksymalnie 10 000 000 ścianek. Ścianki są liczone jako trójkąty: czworokąt liczy się jako 2, a siatka narysowana więcej niż raz liczy się raz na każdą kopię. Powyżej 100 MB plik FBX musi być binarnym FBX 7.1 lub nowszym, a plik GLB lub glTF nie może używać kompresji Draco.

Wymagany jest dokładnie jeden mode zmiany rozmiaru: resize_height, resize_longest_side lub auto_size. Te trzy parametry wzajemnie się wykluczają.

Name
resize_height
Type
number
Description
Zmień rozmiar modelu do określonej wysokości mierzonej w metrach.

Name
resize_longest_side
Type
number
Description
Zmień rozmiar modelu tak, aby jego najdłuższy bok odpowiadał tej wartości, mierzonej w metrach. Proporcje są zachowane.

Name
auto_size
Type
boolean
Description
Gdy ustawione na true, usługa wykorzystuje wizję AI do automatycznego oszacowania rzeczywistej wysokości obiektu i odpowiednio zmienia rozmiar modelu. Punkt początkowy domyślnie przyjmie wartość bottom, chyba że origin_at zostanie jawnie ustawiony.

Name
origin_at
Type
string
domyślne bottom
Description
Pozycja punktu początkowego po zmianie rozmiaru.
Dostępne wartości: bottom, center.

Zwraca

Właściwość result w odpowiedzi zawiera id nowo utworzonego zadania zmiany rozmiaru.

Tryby niepowodzenia

400 - Bad Request

Żądanie było niepoprawne. Typowe przyczyny:

Brakujący parametr: Należy podać model_url lub input_task_id.
Brakujący mode zmiany rozmiaru: Należy podać co najmniej jeden z parametrów resize_height, resize_longest_side lub auto_size.
Wzajemnie wykluczające się parametry: resize_height, resize_longest_side i auto_size nie mogą być łączone.
Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do zakończonego powodzeniem zadania.
Nieprawidłowy format modelu: model_url wskazuje na plik o nieobsługiwanym rozszerzeniu.
Niedostępny URL: Nie udało się pobrać pliku spod model_url.
Plik modelu zbyt duży: Plik wskazany przez model_url przekracza 400 MB (URL http lub https) lub 100 MB (URI data:).
Zbyt wiele ścianek: Plik wskazany przez model_url ma ponad 100 MB i więcej niż 10 000 000 ścianek. Zmniejsz liczbę ścianek, a następnie wyślij plik ponownie.
ASCII FBX powyżej 100 MB: Plik wskazany przez model_url to ASCII FBX przekraczający 100 MB. Wyślij go jako binarny FBX lub GLB.
Nieodczytywalny plik modelu: Plik wskazany przez model_url ma ponad 100 MB i nie można odczytać jego nagłówka, np. w przypadku skompresowanego Draco pliku GLB lub glTF, albo binarnego FBX starszego niż 7.1.
Nagłówek modelu zbyt złożony: Plik wskazany przez model_url ma ponad 100 MB, a jego nagłówek zawiera zbyt wiele siatek, węzłów lub rekordów do sprawdzenia. Zmniejsz liczbę obiektów w pliku, a następnie wyślij go ponownie.

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/resize

# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/resize/:id

Pobierz zadanie Zmień rozmiar

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

Parametry

Name
id
Type
path
Description
ID zadania zmiany rozmiaru do pobrania.

Zwraca

Obiekt zadania Zmień rozmiar.

Request

GET

/openapi/v1/resize/:id

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

Response

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

DELETE/openapi/v1/resize/:id

Usuń zadanie zmiany rozmiaru

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

Parametry ścieżki

Name
id
Type
path
Description
ID zadania zmiany rozmiaru do usunięcia.

Status zadania

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

Zadania, które jest już IN_PROGRESS, nie można usunąć: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie kontynuuje działanie. Kredyty za zadanie, które worker już zaczął przetwarzać, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby Cię 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) jest usuwane bez zwrotu kredytów.

Zwraca

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

Request

DELETE

/openapi/v1/resize/:id

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

Lista zadań zmiany rozmiaru

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

Parametry

Name
page_num
Type
integer
domyślne 1
Description
Numer strony dla 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: Sortowanie według czasu utworzenia rosnąco.
- -created_at: Sortowanie według czasu utworzenia malejąco.

Zwracane dane

Zwraca stronicowaną listę Obiektów zadania zmiany rozmiaru.

Request

GET

/openapi/v1/resize

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

Response

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

GET/openapi/v1/resize/:id/stream

Przesyłaj strumieniowo zadanie zmiany rozmiaru

Ten punkt końcowy przesyła strumieniowo aktualizacje zadania zmiany rozmiaru w czasie rzeczywistym za pomocą Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania zmiany rozmiaru do przesyłania strumieniowego.

Zwraca

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

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

Request

GET

/openapi/v1/resize/:id/stream

curl -N https://api.meshy.ai/openapi/v1/resize/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": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Obiekt zadania Resize

Obiekt Resize Task reprezentuje zadanie zmiany rozmiaru.

Właściwości

id · string

Unikalny identyfikator zadania.

type · string

Typ zadania. Wartość to resize.

model_urls · object

Adres URL do pobrania pliku modelu po zmianie rozmiaru. W przypadku użycia input_task_id wynik jest zawsze w formacie GLB. W przypadku użycia model_url, wejście w formacie .glb, .obj, .fbx lub .stl zachowuje swój format, a wejście .gltf lub Data URI generuje GLB.

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 zadań poprzedzających. Istotne tylko wtedy, gdy status to PENDING.

created_at · timestamp

Znacznik czasu utworzenia zadania, w milisekundach.

started_at · timestamp

Znacznik czasu rozpoczęcia zadania, w milisekundach. 0, jeśli nie rozpoczęto.

finished_at · timestamp

Znacznik czasu zakończenia zadania, w milisekundach. 0, jeśli nie zakończono.

task_error · object

Obiekt błędu, jeśli zadanie zakończyło się niepowodzeniem. Zobacz Błędy, aby uzyskać więcej informacji.

consumed_credits · integer

Liczba kredytów zużytych przez to zadanie (1 kredyt za zadanie zmiany rozmiaru). Zwraca 0 dla zadań FAILED.