API di Conversione

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

POST/openapi/v1/convert

Creare un Task di Conversione

Questo endpoint crea un nuovo task di conversione del formato.

Parametri

Solo uno tra input_task_id o model_url è richiesto. Se entrambi sono forniti, 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 di SUCCEEDED.

Name
model_url
Type
string
Obbligatorio
Description
Un URL o Data URI pubblicamente accessibile che punta a un file modello 3D. Formati supportati: .glb, .gltf, .obj, .fbx, .stl. Per i Data URI, utilizzare 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.

Restituzioni

La proprietà result della risposta contiene l'id del task di conversione appena creato.

Modalità di Fallimento

400 - Bad Request

La richiesta non era accettabile. Cause comuni:

Parametro mancante: Devono essere forniti model_url o input_task_id.
target_formats mancante: Deve essere specificato almeno un formato di destinazione.
Task di input non valido: L'input_task_id deve riferirsi a un task riuscito.
Formato del modello non valido: Il model_url punta a un file con un'estensione non supportata.
URL irraggiungibile: Il model_url non può essere scaricato.

401 - Unauthorized

Autenticazione fallita. Si prega di controllare la 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.

Restituisce

L'oggetto dell'attività di conversione.

Richiesta

GET

/openapi/v1/convert/:id

curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Risposta

{
  "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 Converti

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

Parametri del percorso

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

Restituisce

Restituisce 200 OK in caso di successo.

Richiesta

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

Risposta

// Returns 200 Ok on success.

GET/openapi/v1/convert

Elenco delle attività di conversione

Questo endpoint ti consente di recuperare un elenco di attività 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 della dimensione della pagina. Il massimo consentito è di 50 elementi.

Name
sort_by
Type
string
Description
Campo per l'ordinamento. Valori disponibili:
- +created_at: Ordina per tempo di creazione in ordine crescente.
- -created_at: Ordina per tempo di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato di Gli oggetti attività di conversione.

Richiesta

GET

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Risposta

[
  {
    "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

Trasmetti un'attività di conversione

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

Parametri

Name
id
Type
path
Description
Identificatore univoco per l'attività di conversione da trasmettere.

Restituisce

Restituisce un flusso di Gli oggetti dell'attività di conversione come Server-Sent Events.

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

Richiesta

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

Flusso di Risposta

// 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 Convert Task

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

Proprietà

id · stringa

Identificatore univoco per il compito.

type · stringa

Tipo di compito. Il valore è convert.

model_urls · oggetto

URL scaricabili per i file modello convertiti. Solo i formati specificati in target_formats avranno URL. Altre proprietà di formato saranno stringhe vuote.

progress · intero

Avanzamento del compito (0-100).

status · stringa

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

preceding_tasks · intero

Il conteggio dei compiti precedenti. Significativo solo quando lo stato è PENDING.

created_at · timestamp

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

started_at · timestamp

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

finished_at · timestamp

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

task_error · oggetto

Oggetto errore se il compito è fallito. Vedi Errori per maggiori dettagli.

consumed_credits · intero

Il numero di crediti consumati da questo compito (1 credito per compito di conversione). Restituisce 0 per i compiti FAILED.