Trasforma una foto sorgente in una statuina collezionabile 3D in stile mattoncino in due fasi:
prototipo genera un'immagine concettuale stilizzata dalla tua foto di input, quindi
costruzione trasforma quell'immagine concettuale in un modello 3D con texture. Le due fasi
sono collegate tramite input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Genera un'immagine concettuale in stile mattoncino a partire dalla foto originale. L'ID del task restituito è quello che devi passare come input_task_id all'endpoint di costruzione. Fare riferimento a
L'Oggetto del Task Prototipo di Statuina
per la forma della risposta.
Parametri
Name
image_url
Type
string
Obbligatorio
Description
Foto di origine per Meshy da stilizzare come statuina di mattoncini. Attualmente supportiamo i formati .jpg, .jpeg, .png, e .webp.
Ci sono due modi per fornire l'immagine:
URL pubblicamente accessibile: Un URL che è accessibile da internet pubblico.
Data URI: Un Data URI codificato in base64 dell'immagine. Esempio di un Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Nome opzionale del task per scopi di visualizzazione. Massimo 100 caratteri.
Restituisce
La proprietà result della risposta contiene l'ID del task id del nuovo task prototipo di statuina in mattoncini. Interroga l'endpoint Get a Task o iscriviti al stream fino a quando il task raggiunge SUCCEEDED, quindi passa quell'ID all'endpoint di costruzione come input_task_id.
Modalità di Fallimento
Name
400 - Bad Request
Description
La richiesta è inaccettabile. Cause comuni:
Parametro mancante: image_url è richiesto.
Formato immagine non valido: L' image_url fornito non è un formato supportato (.jpg, .jpeg, .png, .webp).
Dimensioni immagine fuori campo: L'immagine è troppo piccola, supera la dimensione massima del file o supera il conteggio massimo dei pixel.
URL irraggiungibile: L' image_url non può essere scaricato (404 o timeout).
Data URI non valido: La stringa base64 è malformata.
Contenuto segnalato: L'immagine di input è stata segnalata da moderation NSFW o di proprietà intellettuale.
Name
401 - Unauthorized
Description
Autenticazione fallita. Si prega di controllare la chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
403 - Forbidden
Description
L'immagine di input è stata segnalata per violazione della proprietà intellettuale.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.
Request
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Fase 1: genera un'immagine concettuale in stile mattoncinocurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Genera la statuina di mattoncini 3D finale con texture da un'attività di prototipo riuscita. La costruzione esegue la stessa pipeline immagine-in-3D come
Immagine in 3D, quindi il formato dell'oggetto di risposta e l'elenco degli URL di output corrispondono esattamente. Fare riferimento a
L'Oggetto dell'Attività di Costruzione di una Statuina di Mattoncini per la forma della risposta.
Parametri
Name
input_task_id
Type
string
Obbligatorio
Description
L'ID dell'attività di un prototipo creato tramite questo stesso endpoint OpenAPI. Il prototipo deve essere stato creato con la stessa chiave API, deve aver raggiunto SUCCEEDED, e deve aver prodotto esattamente un'immagine candidata.
I prototipi creati tramite il webapp non sono accettati — l'endpoint di costruzione accetta solo prototipi prodotti da POST /openapi/creative-lab/brick-figure/v1/prototype e rifiuta qualsiasi altra fonte con 404.
Name
name
Type
string
Description
Nome dell'attività opzionale a scopo di visualizzazione. Massimo 100 caratteri.
Ritorna
La proprietà result della risposta contiene l'id dell'attività di costruzione della statuina di mattoncini appena creata. Verifica l'endpoint Recupera un'Attività o iscriviti al flusso fino a quando l'attività raggiunge SUCCEEDED, quindi scarica la GLB con texture da model_urls.glb (o la coppia OBJ + MTL da model_urls.obj e model_urls.mtl se la tua pipeline a valle preferisce OBJ).
Modalità di Fallimento
Name
400 - Bad Request
Description
La richiesta era inaccettabile. Cause comuni:
Parametro mancante: input_task_id è richiesto.
UUID non valido: L'input_task_id non è un UUID valido.
Genitore non riuscito: L'attività di prototipo di riferimento non ha ancora raggiunto SUCCEEDED.
Nessun candidato: L'attività di prototipo è stata completata con successo ma non ha prodotto alcuna immagine candidata.
Name
401 - Unauthorized
Description
Autenticazione fallita. Si prega di controllare la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questa attività.
Name
404 - Not Found
Description
L'attività di prototipo di riferimento non esiste, appartiene a un utente diverso o è stata creata tramite il webapp (solo le attività di prototipo in modalità API si concatenano nella costruzione).
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.
Request
POST
/openapi/creative-lab/brick-figure/v1/build
# Fase 2: costruzione a cascata da un'attività di prototipo riuscitacurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Recupera un'attività di prototipo o build data un id valido dell'attività. Il percorso dell'URL
deve corrispondere alla fase dell'attività — un'attività di build recuperata tramite
/prototype/:id restituisce 404, e viceversa.
Cancella un task di statuina di mattoni. Se il task è ancora PENDING, i crediti
consumati al momento della creazione vengono rimborsati. I task che sono già
IN_PROGRESS vengono cancellati senza rimborso (il lavoratore potrebbe già
essere in fase di consumo di risorse). I task che hanno già raggiunto uno stato finale
(SUCCEEDED, FAILED, CANCELED) non possono essere cancellati.
Il percorso dell'URL deve corrispondere alla fase del task — DELETE su
/prototype/:buildId restituisce 404.
Parametri di Percorso
Name
id
Type
path
Description
Identificatore univoco per il task di statuina di mattoni da cancellare.
Restituzioni
Restituisce 204 No Content in caso di successo con un corpo vuoto.
Modalità di Fallimento
Name
400 - Bad Request
Description
Il task è già in uno stato finale e non può essere cancellato.
Name
404 - Not Found
Description
Il task non esiste, appartiene a un utente diverso, o la sua fase non corrisponde al percorso dell'URL.
Emetti aggiornamenti in tempo reale per un compito di statuina tramite Server-Sent Events (SSE).
Il percorso URL deve corrispondere alla fase del compito — l'apertura di un flusso su
/prototype/:buildId/stream emette un singolo event: error payload con
status_code: 404 e chiude il flusso.
Parametri
Name
id
Type
path
Description
Identificatore univoco per il compito di statuina da emettere.
Restituisce
Restituisce un flusso di oggetti compito di Protoipo di Statuina
o di Costruzione di Statuina come
Server-Sent Events. Per compiti PENDING o IN_PROGRESS, il flusso di risposta
includerà solo i campi necessari progress e status.
Recupera un elenco paginato delle tue attività di statuina per una singola fase. Il percorso URL
seleziona la fase — /prototype restituisce le attività prototipo; /build
restituisce le attività di costruzione. Le attività dell'altra fase non sono incluse in nessuna delle
risposte.
Parametri del Percorso
Name
stage
Type
path
Obbligatorio
Description
O prototype o build. La collezione restituisce solo attività
la cui fase corrisponde all'URL — il recupero di /prototype non restituisce mai
attività di costruzione e viceversa.
Parametri di Query
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
predefinito -created_at
Description
Campo per l'ordinamento. Valori disponibili:
+created_at: Ordina per orario di creazione in ordine crescente.
-created_at: Ordina per orario di creazione in ordine decrescente.
# Elenco delle attività prototipocurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"# Elenco delle attività di costruzionecurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"
L'oggetto Task Prototipo Statuina di Mattoni è un'unità di lavoro che Meshy tiene traccia per
generare un'immagine concettuale in stile mattoni da una foto di origine. L'output di
questa fase è concatenato nella fase di costruzione
tramite input_task_id.
Proprietà
Name
id
Type
string
Description
Identificatore univoco per il compito. Anche se utilizziamo un UUID ordinabile k come dettaglio di implementazione per gli id dei compiti, non dovresti fare alcuna supposizione sul formato dell'id.
Name
type
Type
string
Description
Tipo di compito. Il valore è creative-lab-brick-figure-prototype.
Name
name
Type
string
Description
Il nome del compito fornito quando il compito è stato creato. Stringa vuota se non è stato fornito alcun nome.
Name
status
Type
string
Description
Stato del compito. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso del compito. Se il compito non è ancora iniziato, questa proprietà sarà 0. Una volta che il compito è riuscito, questo diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando il compito è stato creato, in millisecondi.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1 gennaio 1970 UTC, seguendo
lo standard RFC 3339.
Ad esempio, venerdì 1 settembre 2023 alle 12:00:00 PM GMT è rappresentato come 1693569600000. Questo si applica
a tutti i timestamp in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp di quando il compito è stato avviato, in millisecondi. Se il compito non è ancora iniziato, questa proprietà sarà null.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il compito è stato completato, in millisecondi. Se il compito non è ancora completato, questa proprietà sarà null.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato del compito scade, in millisecondi.
Name
preceding_tasks
Type
integer
Description
Il conteggio dei compiti precedenti.
Il valore di questo campo è significativo solo se lo stato del compito è PENDING.
Name
task_error
Type
object
Description
Dettagli dell'errore per i compiti falliti. Vedi Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo compito. Presente quando lo stato del compito è PENDING, IN_PROGRESS o SUCCEEDED. Restituisce 0 per i compiti FAILED (i crediti vengono rimborsati in caso di fallimento).
Name
image_urls
Type
array of strings
Description
URL scaricabili per i candidati immagini del concetto generati da questo compito del prototipo. Attualmente l'API restituisce sempre esattamente un candidato; il campo è un array in modo che le revisioni future possano presentare più candidati senza una modifica incompatibile.
L'oggetto Attività di Costruzione Statuina è un'unità di lavoro che Meshy tiene traccia per
generare una statuina in 3D con texture da un'attività di prototipo riuscita.
Utilizza lo stesso processo di trasformazione immagine in 3D utilizzato da Immagine in 3D,
quindi i campi di output rispecchiano quelli dell'endpoint dell'oggetto attività.
Proprietà
Name
id
Type
string
Description
Identificatore univoco per l'attività.
Name
type
Type
string
Description
Tipo dell'attività. Il valore è creative-lab-brick-figure-build.
Name
name
Type
string
Description
Il nome dell'attività fornito quando l'attività è stata creata. Stringa vuota se non è stato fornito alcun nome.
Name
status
Type
string
Description
Stato dell'attività. I valori possibili sono uno di PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress dell'attività. Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta che l'attività è riuscita, questo diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando l'attività è stata creata, in millisecondi.
Name
started_at
Type
timestamp
Description
Timestamp di quando l'attività è stata avviata, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di quando l'attività è stata completata, in millisecondi.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato dell'attività scade, in millisecondi.
Name
preceding_tasks
Type
integer
Description
Il conteggio delle attività precedenti. Significativo solo quando lo stato è PENDING.
Name
task_error
Type
object
Description
Dettagli dell'errore per le attività non riuscite. Vedi Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questa attività. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di errore).
Name
prompt
Type
string
Description
Sempre vuoto per la creazione di statuine in mattoni. Presente per la compatibilità tra endpoint con la forma condivisa V2ImageTo3DTaskResponse utilizzata da Immagine in 3D.
Name
negative_prompt
Type
string
Description
Sempre vuoto per la creazione di statuine in mattoni. Presente per la compatibilità tra endpoint.
Name
texture_prompt
Type
string
Description
Sempre vuoto per la creazione di statuine in mattoni. Presente per la compatibilità tra endpoint.
Name
texture_image_url
Type
string
Description
Sempre vuoto per la creazione di statuine in mattoni. Presente per la compatibilità tra endpoint.
Name
model_urls
Type
object
Description
URL scaricabili per il modello 3D generato. La creazione di statuine in mattoni genera un GLB texturizzato più la coppia OBJ + MTL per pipeline che preferiscono Wavefront OBJ. La forma del campo corrisponde all'oggetto Image to 3D model_urls in modo che le future aggiunte di formato si inseriscano senza una modifica rompente.
Name
glb
Type
string
Description
URL scaricabile per il file GLB texturizzato.
Name
obj
Type
string
Description
URL scaricabile per il file Wavefront OBJ (geometria + UV).
Name
mtl
Type
string
Description
URL scaricabile per il file materiale MTL compagno dell'OBJ. Abbina con obj e l'elemento da texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
URL scaricabile per l'immagine in miniatura del file del modello.
Name
texture_urls
Type
array
Description
Un array di oggetti URL di texture generati da questa attività. Attualmente contiene un singolo oggetto con la mappa del colore di base.
Name
base_color
Type
string
Description
URL scaricabile per l'immagine della mappa del colore di base.
Oggetto di attività di costruzione di statuine in mattoni - Esempio