API Ridimensiona

L'API Ridimensiona consente di ridimensionare modelli 3D esistenti alle dimensioni del mondo reale. È possibile specificare un'altezza esatta, un vincolo sul lato più lungo, oppure lasciare che l'IA stimi automaticamente le dimensioni appropriate.

POST/openapi/v1/resize

Crea un Resize Task

Questo endpoint crea un nuovo task di ridimensionamento.

Il task viene eseguito in background. Per informazioni sulla durata tipica, consulta Tempi di elaborazione.

Parametri

È richiesto solo uno tra input_task_id o model_url. Se vengono forniti entrambi, input_task_id ha la priorità.

Name
input_task_id
Type
string
Obbligatorio
Description
L'ID di un task Meshy completato di cui vuoi ridimensionare il modello. Il task deve avere uno stato SUCCEEDED. Il formato di output sarà GLB.

Name
model_url
Type
string
Obbligatorio
Description
Un URL pubblicamente accessibile o un Data URI che punta a un file di modello 3D. Formati supportati: .glb, .gltf, .obj, .fbx, .stl. Per i Data URI, utilizza il MIME type: application/octet-stream. Il formato di output manterrà il formato originale del modello in ingresso.
Dimensione massima del file: 100 MB.

È richiesta esattamente una modalità di ridimensionamento: resize_height, resize_longest_side o auto_size. Questi tre parametri si escludono a vicenda.

Name
resize_height
Type
number
Description
Ridimensiona il modello a un'altezza specifica misurata in metri.

Name
resize_longest_side
Type
number
Description
Ridimensiona il modello in modo che il suo lato più lungo corrisponda a questo valore, misurato in metri. Il rapporto d'aspetto viene mantenuto.

Name
auto_size
Type
boolean
Description
Quando impostato su true, il servizio utilizza la visione artificiale per stimare automaticamente l'altezza reale dell'oggetto e ridimensionare il modello di conseguenza. L'origine sarà impostata su bottom per impostazione predefinita, a meno che origin_at non venga impostato esplicitamente.

Name
origin_at
Type
string
predefinito bottom
Description
Posizione dell'origine dopo il ridimensionamento.
Valori disponibili: bottom, center.

Valori restituiti

La proprietà result della risposta contiene l'id del nuovo task di ridimensionamento creato.

Modalità di errore

400 - Bad Request

La richiesta non è stata accettata. Cause comuni:

Parametro mancante: deve essere fornito model_url oppure input_task_id.
Modalità di ridimensionamento mancante: deve essere specificato almeno uno tra resize_height, resize_longest_side o auto_size.
Parametri mutuamente esclusivi: resize_height, resize_longest_side e auto_size non possono essere combinati.
Task di input non valido: input_task_id deve fare riferimento a un task completato con successo.
Formato del modello non valido: model_url punta a un file con un'estensione non supportata.
URL non raggiungibile: non è stato possibile scaricare model_url.
File del modello troppo grande: il file indicato in model_url supera i 100 MB.

401 - Unauthorized

Autenticazione non riuscita. Verifica la tua chiave API.

402 - Payment Required

Crediti insufficienti per eseguire questo task.

429 - Too Many Requests

Hai superato il tuo limite di frequenza.

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

Recupera un'attività di ridimensionamento

Questo endpoint recupera un'attività di ridimensionamento tramite il suo ID.

Parametri

Name
id
Type
path
Description
L'ID dell'attività di ridimensionamento da recuperare.

Restituisce

L'oggetto Resize Task.

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

Elimina un'attività di ridimensionamento

Questo endpoint elimina definitivamente un'attività di ridimensionamento, inclusi tutti i modelli e i dati associati. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività di ridimensionamento da eliminare.

Stato dell'attività

Un'attività ancora in stato PENDING viene eliminata e i crediti consumati al momento della creazione vengono rimborsati.

Un'attività già in stato IN_PROGRESS non può essere eliminata: la richiesta viene rifiutata con 409 Conflict e l'attività continua a essere eseguita. I crediti per un'attività che il worker ha già iniziato a elaborare non sono rimborsabili, quindi eliminarla a metà esecuzione ti costerebbe sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Un'attività in uno stato terminale (SUCCEEDED, FAILED o CANCELED) viene eliminata senza rimborso.

Restituisce

Restituisce 200 OK in caso di successo, oppure 409 Conflict quando l'attività è in stato 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

Elenca le attività di ridimensionamento

Questo endpoint consente di recuperare un elenco di attività di ridimensionamento.

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Numero di pagina per la paginazione.

Name
page_size
Type
integer
predefinito 10
Description
Limite di dimensione della pagina. Il massimo consentito è 100 elementi.

Name
sort_by
Type
string
Description
Campo in base al quale ordinare. Valori disponibili:
- +created_at: Ordina per data di creazione in ordine crescente.
- -created_at: Ordina per data di creazione in ordine decrescente.

Valori restituiti

Restituisce un elenco paginato di Oggetti Attività di Ridimensionamento.

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

Trasmetti in streaming un'attività di ridimensionamento

Questo endpoint trasmette in streaming gli aggiornamenti in tempo reale per un'attività di ridimensionamento utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività di ridimensionamento da trasmettere in streaming.

Restituisce

Restituisce un flusso di oggetti Attività di Ridimensionamento come Server-Sent Events.

Per le attività PENDING o IN_PROGRESS, il flusso di risposta includerà solo i campi progress e status necessari.

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
}

L'oggetto Resize Task

L'oggetto Resize Task rappresenta un lavoro di ridimensionamento.

Proprietà

id · string

Identificatore univoco del task.

type · string

Tipo del task. Il valore è resize.

model_urls · object

URL scaricabile per il file del modello ridimensionato. Quando si utilizza input_task_id, l'output è sempre GLB. Quando si utilizza model_url, l'output preserva il formato originale.

progress · integer

Progress del task (0-100).

status · string

Status del task. Valori possibili: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Il numero di task precedenti. Significativo solo quando lo status è PENDING.

created_at · timestamp

Timestamp di quando il task è stato creato, in millisecondi.

started_at · timestamp

Timestamp di quando il task è stato avviato, in millisecondi. 0 se non è stato avviato.

finished_at · timestamp

Timestamp di quando il task è terminato, in millisecondi. 0 se non è terminato.

task_error · object

Oggetto errore se il task è fallito. Consulta Errori per maggiori dettagli.

consumed_credits · integer

Il numero di crediti consumati da questo task (1 credito per ogni task di ridimensionamento). Restituisce 0 per i task FAILED.