API Converti

Converti un modello 3D in altri formati di file, da un'attività Meshy o da un file modello.

POST/openapi/v1/convert

Crea un task di Convert

Crea un task di Convert. Il task viene eseguito in background. Per sapere quanto tempo richiede solitamente un task, consulta Tempi di elaborazione.

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

Parametri

Name
input_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii model_url. L'ID del task Meshy il cui modello vuoi convertire. Il task deve avere lo stato SUCCEEDED.

Name
model_url
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii input_task_id. Il modello da convertire, come URL pubblico o data URI. Se invii entrambi, Meshy usa input_task_id.
Il modello deve essere un file GLB, glTF, OBJ, FBX o STL di al massimo 400 MB proveniente da un URL http o https, oppure di 100 MB come data URI. Per un data URI, usa il MIME type application/octet-stream.
Un file di oltre 100 MB deve inoltre rispettare queste regole:
- Un file GLB, glTF, FBX o OBJ può avere al massimo 10.000.000 di facce. Meshy conta le facce come triangoli, quindi un quad conta come 2, e una mesh disegnata più volte conta una volta per copia.
- Un file FBX deve essere binario, FBX 7.1 o versione successiva.
- Un file GLB o glTF non deve usare la compressione Draco.

Name
target_formats
Type
string[]
Obbligatorio
Description
I formati di file da generare. Elencane almeno uno. Un elenco mancante o vuoto restituisce 400.
Valori disponibili:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task di Convert.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato rilevato. Ad esempio:
- Parametro mancante: non è stato inviato né model_url né input_task_id.
- target_formats mancante: target_formats è assente o non elenca alcun formato.
- Task di input non valido: input_task_id non corrisponde a un task completato con successo.
- Formato del modello non valido: il file model_url ha un'estensione non supportata.
- URL irraggiungibile: Meshy non riesce a scaricare il file model_url.
- File del modello troppo grande: il file model_url supera i 400 MB da un URL http o https, oppure supera i 100 MB come data URI.
- Troppe facce: il file model_url supera i 100 MB e ha più di 10.000.000 di facce. Riduci il numero di facce, quindi invia nuovamente il file.
- FBX ASCII oltre 100 MB: il file model_url è un FBX ASCII che supera i 100 MB. Invialo come FBX binario o GLB.
- File del modello illeggibile: il file model_url supera i 100 MB e Meshy non riesce a leggerne l'intestazione. Ad esempio, è un GLB o glTF compresso con Draco, oppure un FBX binario precedente alla versione 7.1.
- Intestazione del modello troppo complessa: il file model_url supera i 100 MB e la sua intestazione ha troppe mesh, nodi o record da controllare. Riduci il numero di oggetti nel file, quindi invialo nuovamente.
Correggi la richiesta, quindi inviala di nuovo. Consulta Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Ad esempio:
- Crediti insufficienti: l'account non ha crediti sufficienti per questo task, oppure l'account ha raggiunto un limite di credito. Controlla il tuo saldo crediti, quindi riprova.
- Piano gratuito: la creazione di un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
Name
403 - Forbidden
Description
input_task_id è un modello bassorilievo, che questo endpoint non può convertire. Il messaggio è This model type does not support this operation. Invia un modello diverso.
Name
404 - Not Found
Description
input_task_id non corrisponde a nessuno dei tuoi task. Controlla l'ID del task, quindi invia di nuovo la richiesta.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, quindi riprova. Consulta Limiti di frequenza.

GET/openapi/v1/convert/:id

Recupera un task di Convert

Restituisce un task di Convert tramite il suo ID.

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

Parametri

Name
id
Type
path
Description
L'ID del task ottenuto dalla risposta di creazione.

Restituisce

L'oggetto task di Convert.

DELETE/openapi/v1/convert/:id

Elimina un task di Convert

Elimina definitivamente un task di Convert, inclusi i suoi modelli e dati. Non puoi annullare un'eliminazione.

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

Parametri del percorso

Name
id
Type
path
Description
L'ID del task da eliminare.

Stato del task

Eliminare un task PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un task IN_PROGRESS non può essere eliminato. La richiesta restituisce 409 Conflict, e il task continua a essere eseguito. Meshy non rimborsa un task già avviato, quindi eliminarlo ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminalo.

Eliminare un task in uno stato finale (SUCCEEDED, FAILED o CANCELED) non rimborsa i suoi crediti.

Risultati restituiti

200 OK quando il task viene eliminato, oppure 409 Conflict quando il task è IN_PROGRESS.

GET/openapi/v1/convert

Elenca i task di Convert

Restituisce un elenco dei tuoi task di Convert.

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

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Il numero di pagina da restituire.

Name
page_size
Type
integer
predefinito 10
Description
Il numero di task per pagina, fino a 100.

Name
sort_by
Type
string
Description
L'ordine di ordinamento.
Valori disponibili:
- +created_at: dal più vecchio
- -created_at: dal più recente

Restituisce

Un elenco paginato di oggetti task di Convert.

GET/openapi/v1/convert/:id/stream

Esegui lo streaming di un'attività di conversione

Esegue lo streaming degli aggiornamenti di un'attività di conversione come Server-Sent Events (SSE).

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
}

Parametri

Name
id
Type
path
Description
L'ID dell'attività proveniente dalla risposta di creazione.

Risultati restituiti

Uno stream di oggetti attività di conversione come Server-Sent Events.

Ogni evento contiene l'oggetto attività completo, nello stesso formato restituito dall'endpoint Get. Finché l'attività è PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora alcun valore.

L'oggetto task Convert

Un oggetto task Convert descrive una conversione di formato di un modello 3D. Contiene lo stato, il progresso e i file del modello quando il task ha successo.

Proprietà

Name
id
Type
string
Description
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre convert.
Name
model_urls
Type
object
Description
Gli URL di download per il modello convertito, uno per ogni formato di file. Solo i formati presenti in target_formats hanno degli URL. Un formato che non hai richiesto non ha una chiave, anziché avere una stringa vuota.
Name
progress
Type
integer
Description
Quanta parte del task è stata completata, in percentuale. È 0 finché il task non parte ed è 100 quando ha successo.
Name
status
Type
string
Description
Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
preceding_tasks
Type
integer
Description
Il numero di task che precedono questo nella coda. Il valore è significativo solo mentre il task è PENDING.
Name
created_at
Type
timestamp
Description
L'orario in cui il task è stato creato, in millisecondi Unix.
Name
started_at
Type
timestamp
Description
L'orario in cui il task è partito, in millisecondi Unix. È 0 finché il task non parte.
Name
finished_at
Type
timestamp
Description
L'orario in cui il task è terminato, in millisecondi Unix. È 0 finché il task non termina.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati dal task, che è 1 per un task Convert. È 0 per un task FAILED.