Convert API

L'API Convert ti permette di convertire modelli 3D esistenti in formati di file diversi.

POST/openapi/v1/convert

Creare un Task di Conversione

Questo endpoint crea un nuovo task di conversione di formato.

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 il cui modello si desidera convertire. Il task deve avere uno stato SUCCEEDED.

Name
model_url
Type
string
Obbligatorio
Description
Un URL pubblicamente accessibile o una Data URI che punta a un file di modello 3D. Formati supportati: .glb, .gltf, .obj, .fbx, .stl. Per le Data URI, usare il MIME type: application/octet-stream.

Name
target_formats
Type
string[]
Obbligatorio
Description
Un elenco di formati di output per il modello convertito. Valori disponibili: glb, fbx, obj, usdz, blend, stl, 3mf.

Valori restituiti

La proprietà result della risposta contiene l'id del task di conversione appena 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.
target_formats mancante: deve essere specificato almeno un formato di destinazione.
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 irraggiungibile: non è stato possibile scaricare model_url.

401 - Unauthorized

Autenticazione fallita. 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/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

Recupera un'attività di conversione

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

Parametri

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

Valori restituiti

L'oggetto dell'attività di conversione (Convert Task).

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

Elimina un'attività di conversione

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

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività di conversione 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_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 non sono rimborsabili, quindi eliminarla a metà esecuzione ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

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

Restituisce

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

Elenca task di conversione

Questo endpoint consente di recuperare un elenco di task di conversione.

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 per l'ordinamento. 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 Task di Conversione.

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

Effettua lo streaming di un'attività di conversione

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

Parametri

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

Valori restituiti

Restituisce uno stream di The Convert Task Objects come Server-Sent Events.

Per le attività PENDING o IN_PROGRESS, lo stream di risposta includerà solo i campi necessari progress e 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
}

L'oggetto Task di conversione

L'oggetto Task di conversione rappresenta un lavoro di conversione di formato.

Proprietà

id · string

Identificatore univoco del task.

type · string

Tipo del task. Il valore è convert.

model_urls · object

URL scaricabili per i file del modello convertito. Solo i formati specificati in target_formats avranno degli URL. Le altre proprietà di formato saranno stringhe vuote.

progress · integer

Progresso del task (0-100).

status · string

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

preceding_tasks · integer

Il numero di task precedenti. Significativo solo quando lo stato è 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 avviato.

finished_at · timestamp

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

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 task di conversione). Restituisce 0 per i task FAILED.