lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. Cambia modello prima di queste date per evitare errori nelle richieste. Vedi tutte le deprecazioni

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 Convert

Crea un task Convert. Il task viene eseguito in background. Per sapere quanto tempo richiede di solito 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 di un task che ha prodotto un modello 3D, ad esempio un task Testo in 3D, Immagine in 3D, Remesh, Ridimensiona o Retexture. Il task deve provenire dall'API e 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 da un URL http o https, oppure 100 MB come Data URI. Per un Data URI, usa il MIME type application/octet-stream.

    Un file di oltre 100 MB deve anche 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 ogni copia.
    • Un file FBX deve essere FBX binario 7.1 o successivo.
    • 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

Restituisce

Il campo result della risposta contiene l'ID del nuovo task 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 manca o non elenca alcun formato.
    • Task di input non valido: input_task_id non è un task API riuscito con un file modello.
    • Formato modello non valido: Il file model_url ha un'estensione non supportata.
    • URL non raggiungibile: Meshy non riesce a scaricare il file model_url.
    • File 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, poi invia di nuovo 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 modello illeggibile: Il file model_url supera i 100 MB e Meshy non riesce a leggerne l'header. Ad esempio, è un GLB o glTF compresso con Draco, oppure un FBX binario precedente alla versione 7.1.
    • Header del modello troppo complesso: Il file model_url supera i 100 MB e il suo header ha troppe mesh, nodi o record da verificare. Riduci il numero di oggetti nel file, poi invialo di nuovo.

    Correggi la richiesta, poi 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 crediti. Controlla il tuo saldo crediti, poi riprova.
    • Piano gratuito: Creare un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, poi riprova.
  • Name
    403 - Forbidden
    Description

    input_task_id è un modello a 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, poi invia di nuovo la richiesta.

  • Name
    429 - Too Many Requests
    Description

    Hai superato il tuo limite di frequenza. Attendi, poi 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 le attività di Convert

Restituisce un elenco delle tue attività 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, fino a 255. Un valore maggiore restituisce 400.

  • Name
    page_size
    Type
    integer
    predefinito 10
    Description

    Il numero di attività 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 attività 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 progress 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

    URL di download per il modello convertito, uno per ogni formato di file. Solo i formati in target_formats hanno URL. Un formato che non hai richiesto non ha una chiave, anziché una stringa vuota.

  • Name
    progress
    Type
    integer
    Description

    Quanto del task è stato completato, in percentuale. È 0 finché il task non inizia e 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

    Ora di creazione del task, in millisecondi Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Ora di avvio del task, in millisecondi Unix. È 0 finché il task non inizia.

  • Name
    finished_at
    Type
    timestamp
    Description

    Ora di conclusione del task, in millisecondi Unix. È 0 finché il task non termina.

  • Name
    expires_at
    Type
    timestamp
    Description

    Ora in cui gli URL di download del task scadono, in millisecondi Unix. È 0 finché il task non termina.

  • Name
    texture_urls
    Type
    array
    Description

    URL di download per le texture del modello, quando il task ha successo: un array di oggetti, uno per ogni set di texture. Ogni oggetto ha un URL base_color e può anche avere URL metallic, roughness, normal, emission e metallic_roughness. È null finché il task non ha successo, ed è un array vuoto quando il modello non ha texture.

  • 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.