API zmiany rozmiaru

API zmiany rozmiaru 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ć AI automatycznie oszacować odpowiedni rozmiar.

POST/openapi/v1/resize

Utwórz zadanie zmiany rozmiaru

Ten punkt końcowy tworzy nowe zadanie zmiany rozmiaru.

Parametry

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

Name
input_task_id
Type
string
Wymagane
Description
Identyfikator 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 data URI 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. Format wyjściowy zachowa oryginalny format modelu wejściowego.

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

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

Name
resize_longest_side
Type
number
Description
Zmienia 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 odpowiedniego dostosowania rozmiaru modelu. Punkt początkowy domyślnie przyjmuje wartość bottom, chyba że origin_at zostanie jawnie ustawione.

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 odpowiedzi zawiera id nowo utworzonego zadania zmiany rozmiaru.

Tryby awarii

400 - Bad Request

Żądanie było niepoprawne. Typowe przyczyny:

Brakujący parametr: Musi być podany model_url lub input_task_id.
Brakujący tryb zmiany rozmiaru: Musi być określony co najmniej jeden z parametrów resize_height, resize_longest_side lub auto_size.
Parametry wzajemnie się wykluczające: resize_height, resize_longest_side i auto_size nie mogą być łączone.
Nieprawidłowe zadanie wejściowe: input_task_id musi wskazywać na pomyślnie ukończone zadanie.
Nieprawidłowy format modelu: model_url wskazuje na plik z nieobsługiwanym rozszerzeniem.
Niedostępny URL: Nie udało się pobrać 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/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 zmiany rozmiaru

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

Parametry

Name
id
Type
path
Description
ID zadania zmiany rozmiaru, które ma zostać pobrane.

Zwraca

Obiekt zadania zmiany rozmiaru.

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 Zmień rozmiar

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

Parametry ścieżki

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

Status zadania

Zadanie, które nadal ma status PENDING, jest usuwane, a kredyty zużyte w momencie utworzenia 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 działa. Kredyty za zadanie, które worker już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania 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) 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 do stronicowania.

Name
page_size
Type
integer
domyślne 10
Description
Limit rozmiaru strony. Maksymalna dopuszczalna 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 w porządku rosnącym.
- -created_at: Sortowanie według czasu utworzenia w porządku malejącym.

Zwraca

Zwraca listę stronicowaną obiektów Obiekt 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

Strumieniowanie zadania Zmień rozmiar

Ten punkt końcowy strumieniuje aktualizacje zadania zmiany rozmiaru w czasie rzeczywistym przy użyciu Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania zmiany rozmiaru do strumieniowania.

Zwraca

Zwraca strumień obiektów zadania Zmień rozmiar 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
}

The Resize Task Object

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 o zmienionym rozmiarze. Podczas używania input_task_id, wynikiem jest zawsze GLB. Podczas używania model_url, format wyjściowy zachowuje oryginalny format.

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. Ma znaczenie 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 się nie powiodło. 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.