API zmiany rozmiaru

Zmień rozmiar modelu 3D do rzeczywistego rozmiaru, w metrach. Ustaw jego wysokość lub długość najdłuższego boku, albo pozwól Meshy oszacować rzeczywistą wysokość obiektu.

POST/openapi/v1/resize

Utwórz zadanie Resize

Tworzy zadanie Resize. Zadanie działa w tle. Informacje o tym, ile zwykle trwa zadanie, znajdziesz w Czasach przetwarzania.

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"
}

Parametry

Name
input_task_id
Type
string
Wymagane
Description
Wymagane, chyba że wysyłasz model_url. ID zadania, które wygenerowało model 3D, na przykład zadania Tekst na 3D, Obraz na 3D, Remesh lub Reteksturowanie. Zadanie musi pochodzić z API i mieć status SUCCEEDED. Meshy zwraca zmieniony rozmiarowo model jako plik GLB.

Name
model_url
Type
string
Wymagane
Description
Wymagane, chyba że wysyłasz input_task_id. Model do zmiany rozmiaru, jako publiczny URL lub Data URI. Jeśli wyślesz oba, Meshy używa input_task_id.
Model musi być plikiem GLB, glTF, OBJ, FBX lub STL o rozmiarze maksymalnie 400 MB z adresu URL http lub https, lub 100 MB jako Data URI. W przypadku Data URI użyj typu MIME application/octet-stream.
Plik powyżej 100 MB musi również spełniać następujące zasady:
- Plik GLB, glTF, FBX lub OBJ może mieć maksymalnie 10 000 000 ścianek. Meshy liczy ścianki jako trójkąty, więc czworokąt liczy się jako 2, a siatka narysowana więcej niż raz liczy się raz na kopię.
- Plik FBX musi być binarnym FBX w wersji 7.1 lub nowszej.
- Plik GLB lub glTF nie może używać kompresji Draco.
Plik GLB, OBJ, FBX lub STL zachowuje swój format w wyniku. Plik .gltf lub Data URI wraca jako GLB.

Wyślij dokładnie jeden z parametrów resize_height, resize_longest_side lub auto_size. Wysłanie żadnego z nich lub więcej niż jednego zwraca 400.

Name
resize_height
Type
number
Description
Nowa wysokość modelu w metrach, większa od 0. Wartość ujemna zwraca 400.

Name
resize_longest_side
Type
number
Description
Nowa długość najdłuższego boku modelu w metrach, większa od 0. Wartość ujemna zwraca 400. Meshy zachowuje proporcje modelu.

Name
auto_size
Type
boolean
Description
Czy oszacować rzeczywistą wysokość obiektu za pomocą AI vision i zmienić rozmiar modelu do niej. Jeśli nie ustawisz origin_at, Meshy umieszcza punkt początkowy na dole.

Name
origin_at
Type
string
domyślne bottom
Description
Gdzie umieścić punkt początkowy modelu po zmianie rozmiaru, bottom lub center.

Zwraca

Pole result odpowiedzi zawiera ID nowego zadania Resize.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat o błędzie wskazuje, jaki problem został wykryty. Na przykład:
- Brakujący parametr: Nie wysłano ani model_url, ani input_task_id.
- Brakujący tryb zmiany rozmiaru: Nie wysłano żadnego z resize_height, resize_longest_side ani auto_size.
- Parametry wzajemnie wykluczające się: Żądanie zawiera więcej niż jeden z parametrów resize_height, resize_longest_side i auto_size. Wyślij tylko jeden.
- Ujemny rozmiar: resize_height lub resize_longest_side ma wartość ujemną.
- Nieprawidłowe zadanie wejściowe: input_task_id nie jest udanym zadaniem API z plikiem modelu.
- Nieprawidłowy format modelu: Plik model_url ma nieobsługiwane rozszerzenie.
- Niedostępny URL: Meshy nie może pobrać pliku model_url.
- Plik modelu zbyt duży: Plik model_url przekracza 400 MB z adresu URL http lub https, lub przekracza 100 MB jako Data URI.
- Zbyt wiele ścianek: Plik model_url przekracza 100 MB i ma więcej niż 10 000 000 ścianek. Zmniejsz liczbę ścianek, a następnie wyślij plik ponownie.
- ASCII FBX powyżej 100 MB: Plik model_url to ASCII FBX przekraczający 100 MB. Wyślij go jako binarny FBX lub GLB.
- Nieodczytywalny plik modelu: Plik model_url przekracza 100 MB, a Meshy nie może odczytać jego nagłówka. Na przykład jest to skompresowany Draco plik GLB lub glTF, lub binarny FBX starszy niż 7.1.
- Nagłówek modelu zbyt złożony: Plik model_url przekracza 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.
Popraw żądanie, a następnie wyślij je ponownie. Zobacz Błędy.
Name
401 - Unauthorized
Description
Brak klucza API lub klucz API jest nieprawidłowy. Sprawdź nagłówek Authorization.
Name
402 - Payment Required
Description
Na przykład:
- Niewystarczające kredyty: Konto nie ma wystarczającej liczby kredytów na to zadanie lub konto osiągnęło limit kredytów. Sprawdź saldo kredytów, a następnie spróbuj ponownie.
- Plan bezpłatny: Utworzenie zadania wymaga płatnego planu. Zaktualizuj swój plan w ustawieniach subskrypcji, a następnie spróbuj ponownie.
Name
403 - Forbidden
Description
input_task_id to model płaskorzeźby, którego ten punkt końcowy nie może zmienić rozmiaru. Komunikat to This model type does not support this operation. Wyślij inny model.
Name
404 - Not Found
Description
input_task_id nie pasuje do żadnego z Twoich zadań. Sprawdź ID zadania, a następnie wyślij żądanie ponownie.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Poczekaj, a następnie spróbuj ponownie. Zobacz Limity szybkości.

GET/openapi/v1/resize/:id

Pobierz zadanie Zmień rozmiar

Zwraca zadanie Zmień rozmiar na podstawie jego ID.

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
}

Parametry

Name
id
Type
path
Description
ID zadania z odpowiedzi utworzenia.

Zwraca

Obiekt zadania Zmień rozmiar.

DELETE/openapi/v1/resize/:id

Usuń zadanie Zmień rozmiar

Trwale usuwa zadanie Zmień rozmiar, w tym jego modele i dane. Usunięcia nie można cofnąć.

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 keeps 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."
}

Parametry ścieżki

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

Status zadania

Usunięcie zadania w statusie PENDING zwraca kredyty użyte podczas jego tworzenia.

Zadania w statusie IN_PROGRESS nie można usunąć. Żądanie zwraca 409 Conflict, a zadanie nadal się wykonuje. Meshy nie zwraca kredytów za zadanie, które już się rozpoczęło, więc jego usunięcie kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Usunięcie zadania w statusie końcowym (SUCCEEDED, FAILED lub CANCELED) nie zwraca jego kredytów.

Zwraca

200 OK, gdy zadanie zostało usunięte, lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

GET/openapi/v1/resize

Lista zadań Zmień rozmiar

Zwraca listę Twoich zadań Zmień rozmiar.

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
  }
]

Parametry

Name
page_num
Type
integer
domyślne 1
Description
Numer strony do zwrócenia, maksymalnie 255. Większa wartość zwróci 400.

Name
page_size
Type
integer
domyślne 10
Description
Liczba zadań na stronę, maksymalnie 100.

Name
sort_by
Type
string
Description
Kolejność sortowania.
Dostępne wartości:
- +created_at: od najstarszych
- -created_at: od najnowszych

Zwraca

Stronicowaną listę obiektów zadań Zmień rozmiar.

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

Przesyłaj strumieniowo zadanie Zmień rozmiar

Przesyła strumieniowo aktualizacje zadania Zmień rozmiar jako Server-Sent Events (SSE).

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
}

Parametry

Name
id
Type
path
Description
ID zadania z odpowiedzi tworzenia.

Zwraca

Strumień obiektów zadania Zmień rozmiar jako Server-Sent Events.

Każde zdarzenie zawiera pełny obiekt zadania, w tej samej postaci, jaką zwraca punkt końcowy Get. Gdy zadanie ma status PENDING lub IN_PROGRESS, jego pola wynikowe nie mają jeszcze wartości.

Obiekt zadania Resize

Obiekt zadania Resize opisuje pojedynczą zmianę rozmiaru modelu 3D. Zawiera status, progress oraz plik modelu, gdy zadanie zakończy się powodzeniem.

Właściwości

Name
id
Type
string
Description
ID zadania. Traktuj go jako nieprzezroczysty ciąg znaków i nie polegaj na jego formacie.
Name
type
Type
string
Description
Typ zadania, zawsze resize.
Name
model_urls
Type
object
Description
Adres URL do pobrania pliku modelu po zmianie rozmiaru. Dla input_task_id plik jest zawsze w formacie GLB. Dla model_url plik GLB, OBJ, FBX lub STL zachowuje swój format, a plik .gltf lub Data URI zostaje zwrócony jako GLB.
Name
progress
Type
integer
Description
Jaka część zadania została ukończona, wyrażona w procentach. Wynosi 0, dopóki zadanie się nie rozpocznie, i 100, gdy zakończy się powodzeniem.
Name
status
Type
string
Description
Status zadania, jeden z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED lub CANCELED.
Name
preceding_tasks
Type
integer
Description
Liczba zadań znajdujących się przed tym zadaniem w kolejce. Wartość ta ma znaczenie tylko wtedy, gdy zadanie ma status PENDING.
Name
created_at
Type
timestamp
Description
Czas utworzenia zadania, w milisekundach Unix.
Name
started_at
Type
timestamp
Description
Czas rozpoczęcia zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie rozpocznie.
Name
finished_at
Type
timestamp
Description
Czas zakończenia zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie zakończy.
Name
expires_at
Type
timestamp
Description
Czas wygaśnięcia adresów URL do pobrania dla zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie zakończy.
Name
texture_urls
Type
array
Description
Adresy URL do pobrania map tekstur modelu, gdy zadanie zakończy się powodzeniem: tablica obiektów, po jednym na każdy zestaw tekstur. Każdy obiekt zawiera adres URL base_color, a może też zawierać adresy URL metallic, roughness, normal, emission i metallic_roughness. Wartość ta wynosi null, dopóki zadanie się nie zakończy powodzeniem, oraz jest pustą tablicą, gdy model nie ma map tekstur.
Name
task_error
Type
object
Description
Szczegóły błędu, gdy zadanie zakończy się niepowodzeniem. Zobacz Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez zadanie, która wynosi 1 dla zadania Resize. Wynosi 0 dla zadania FAILED.