API Converti

L'API Converti ti consente di convertire modelli 3D esistenti in diversi formati di file.

POST/openapi/v1/convert

Crea un'attività Converti

Questo endpoint crea una nuova attività di conversione del 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'attività Meshy completata il cui modello desideri convertire. L'attività deve avere uno stato di SUCCEEDED.

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, usa 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.

Restituisce

La proprietà result della risposta contiene l'id dell'attività di conversione appena creata.

Modalità di errore

400 - Bad Request

La richiesta non era accettabile. Cause comuni:

Parametro mancante: Deve essere fornito model_url o input_task_id.
target_formats mancante: Deve essere specificato almeno un formato di destinazione.
Attività di input non valida: input_task_id deve fare riferimento a un'attività riuscita.
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.

401 - Unauthorized

Autenticazione non riuscita. Controlla la tua chiave API.

402 - Payment Required

Crediti insufficienti per eseguire questa attività.

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à Converti

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.

Restituisce

L'oggetto dell'attività Converti.

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à Converti

Questo endpoint elimina definitivamente 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.

Restituisce

Restituisce 200 OK in caso di successo.

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

// Returns 200 Ok on success.

GET/openapi/v1/convert

Elenca attività di Converti

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

Parametri

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

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

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

Restituisce

Restituisce un elenco paginato di Oggetti attività di Converti.

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

Streaming di un'attività Converti

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

Parametri

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

Restituisce

Restituisce uno stream di Gli oggetti attività Converti 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
}

Oggetto dell'attività Converti

L'oggetto attività Converti rappresenta un processo di conversione del formato.

Proprietà

id · string

Identificatore univoco dell'attività.

type · string

Tipo dell'attività. Il valore è convert.

model_urls · object

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

progress · integer

Avanzamento dell'attività (0-100).

status · string

Stato dell'attività. Valori possibili: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Il numero di attività precedenti. Significativo solo quando lo stato è PENDING.

created_at · timestamp

timestamp di quando l'attività è stata creata, in millisecondi.

started_at · timestamp

timestamp di quando l'attività è stata avviata, in millisecondi. 0 se non avviata.

finished_at · timestamp

timestamp di quando l'attività è stata completata, in millisecondi. 0 se non completata.

task_error · object

Oggetto di errore se l'attività non è riuscita. Consulta Errori per maggiori dettagli.

consumed_credits · integer

Il numero di crediti consumati da questa attività (1 credito per attività di conversione). Restituisce 0 per le attività FAILED.