Trasforma una foto sorgente in una statuina collezionabile 3D con testa grande 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/vinyl-figure/v1/prototype
Genera un'immagine concettuale in stile statuina in vinile a partire dalla foto sorgente. L'ID dell'attività restituito è quello che devi passare come input_task_id all'endpoint di build. Consulta
L'oggetto attività prototipo di statuina in vinile
per la forma della risposta.
Parametri
Name
image_url
Type
string
Obbligatorio
Description
Foto sorgente per Meshy da stilizzare come una statuina in vinile con testa grande. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.
Ci sono due modi per fornire l'immagine:
URL pubblicamente accessibile: Un URL 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 dell'attività opzionale per scopi di visualizzazione. Massimo 100 caratteri.
Name
remove_background
Type
boolean
predefinito false
Description
Quando impostato su true, l'immagine prototipo viene restituita come un PNG RGBA trasparente con lo sfondo rimosso, in modo da poter comporre il soggetto su qualsiasi sfondo.
Restituisce
La proprietà result della risposta contiene l'ID dell'attività di prototipo di statuina in vinile appena creata. Interroga l'endpoint Ottieni un'attività o iscriviti al flusso fino a quando l'attività raggiunge SUCCEEDED, quindi passa quell'ID all'endpoint di build come input_task_id.
Modalità di fallimento
Name
400 - Bad Request
Description
La richiesta non è accettabile. Cause comuni:
Parametro mancante: image_url è richiesto.
Formato immagine non valido: L'image_url fornito non è in un formato supportato (.jpg, .jpeg, .png, .webp).
Dimensioni immagine fuori intervallo: 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 dalla moderation NSFW o di proprietà intellettuale.
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
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.
Richiesta
POST
/openapi/creative-lab/vinyl-figure/v1/prototype
# Stage 1: generate a vinyl-figure-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Risposta
{"result":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Esempio di prototipo
Inizia con una foto sorgente, quindi genera l'immagine prototipo utilizzata dalla fase di build.
Genera la statuina in vinile 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. Consulta L'oggetto attività di costruzione della statuina in vinile 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.
Le attività di prototipo create tramite l'app web non sono accettate — l'endpoint di costruzione accetta solo attività di prototipo prodotte da POST /openapi/creative-lab/vinyl-figure/v1/prototype e rifiuta qualsiasi altra fonte con 404.
Name
name
Type
string
Description
Nome dell'attività opzionale per scopi di visualizzazione. Massimo 100 caratteri.
Restituisce
La proprietà result della risposta contiene l'id dell'attività della statuina in vinile appena creata. Interroga l'endpoint Recupera un'attività o iscriviti al flusso fino a quando l'attività raggiunge SUCCEEDED, quindi scarica il 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 non era accettabile. 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 è riuscita 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 altro utente o è stata creata tramite l'app web (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.
Richiesta
POST
/openapi/creative-lab/vinyl-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de" }'
Recupera un'attività di prototipo o di costruzione dato un valido id dell'attività. Il percorso URL
deve corrispondere alla fase dell'attività — un'attività di costruzione recuperata tramite
/prototype/:id restituisce 404, e viceversa.
Annulla un'attività di statuina in vinile. Se l'attività è ancora PENDING, i crediti
consumati al momento della creazione vengono rimborsati. Le attività che sono già
IN_PROGRESS vengono annullate senza rimborso (il lavoratore potrebbe già essere
in fase di consumo di risorse). Le attività che hanno già raggiunto uno stato terminale
(SUCCEEDED, FAILED, CANCELED) non possono essere annullate.
Il percorso URL deve corrispondere alla fase dell'attività — DELETE su
/prototype/:buildId restituisce 404.
Parametri del percorso
Name
id
Type
path
Description
Identificatore univoco per l'attività di statuina in vinile da annullare.
Restituisce
Restituisce 204 No Content in caso di successo con un corpo vuoto.
Modalità di fallimento
Name
400 - Bad Request
Description
L'attività è già in uno stato terminale e non può essere annullata.
Name
404 - Not Found
Description
L'attività non esiste, appartiene a un utente diverso o la sua fase non corrisponde al percorso URL.
Trasmetti aggiornamenti in tempo reale per un'attività di statuina in vinile tramite Server-Sent Events (SSE). Il percorso URL deve corrispondere alla fase dell'attività — aprire 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 l'attività di statuina in vinile da trasmettere.
Restituisce
Restituisce un flusso di oggetti attività Vinyl Figure Prototype o Vinyl Figure Build come Server-Sent Events. Per le attività 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 in vinile per una singola fase.
Il percorso URL seleziona la fase — /prototype restituisce le attività di 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 raccolta restituisce solo le 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 della dimensione della pagina. Il massimo consentito è di 50 elementi.
Name
sort_by
Type
string
predefinito -created_at
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.
L'oggetto Attività Prototipo Statuina in Vinile è un'unità di lavoro che Meshy tiene traccia
per generare un'immagine concettuale in stile statuina in vinile da una foto sorgente.
L'output di questa fase è collegato alla
fase di costruzione tramite input_task_id.
Proprietà
Name
id
Type
string
Description
Identificatore univoco per l'attività. Anche se utilizziamo un UUID ordinabile per id delle attività come dettaglio di implementazione, non dovresti fare alcuna supposizione sul formato dell'id.
Name
type
Type
string
Description
Tipo di attività. Il valore è creative-lab-vinyl-figure-prototype.
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
Avanzamento dell'attività. Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta che l'attività è riuscita, diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando l'attività è stata creata, 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 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 l'attività è iniziata, in millisecondi. Se l'attività non è ancora iniziata, questa proprietà sarà 0.
Name
finished_at
Type
timestamp
Description
Timestamp di quando l'attività è terminata, in millisecondi. Se l'attività non è ancora terminata, questa proprietà sarà 0.
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.
Il valore di questo campo è significativo solo se lo stato dell'attività è PENDING.
Name
task_error
Type
object
Description
Dettagli dell'errore per le attività fallite. Vedi Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questa attività. Presente quando lo stato dell'attività è PENDING, IN_PROGRESS, o SUCCEEDED. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di fallimento).
Name
image_urls
Type
array of strings
Description
URL scaricabili per i candidati dell'immagine concettuale generati da questa attività prototipo. Attualmente l'API restituisce sempre esattamente un candidato; il campo è un array in modo che le revisioni future possano mostrare più candidati senza una modifica dirompente.
Esempio di Oggetto Attività Prototipo Statuina in Vinile
L'oggetto Attività di Costruzione della Statuina in Vinile è un'unità di lavoro che Meshy tiene traccia per generare una statuina in vinile 3D texturizzata da un'attività prototipo riuscita. Utilizza la stessa pipeline immagine-in-3D usata da Immagine in 3D, quindi i campi di output rispecchiano l'oggetto attività di quell'endpoint.
Proprietà
Name
id
Type
string
Description
Identificatore univoco per l'attività.
Name
type
Type
string
Description
Tipo di attività. Il valore è creative-lab-vinyl-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
Avanzamento dell'attività. Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta che l'attività è riuscita, 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à è iniziata, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di quando l'attività è terminata, 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à fallite. 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 fallimento).
Name
prompt
Type
string
Description
Sempre vuoto per la costruzione della statuina in vinile. Presente per compatibilità cross-endpoint con la forma condivisa V2ImageTo3DTaskResponse usata da Immagine in 3D.
Name
negative_prompt
Type
string
Description
Sempre vuoto per la costruzione della statuina in vinile. Presente per compatibilità cross-endpoint.
Name
texture_prompt
Type
string
Description
Sempre vuoto per la costruzione della statuina in vinile. Presente per compatibilità cross-endpoint.
Name
texture_image_url
Type
string
Description
Sempre vuoto per la costruzione della statuina in vinile. Presente per compatibilità cross-endpoint.
Name
model_urls
Type
object
Description
URL scaricabili per il modello 3D generato. La costruzione della statuina in vinile emette 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 un cambiamento radicale.
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 miniatura del file 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 base.
Name
base_color
Type
string
Description
URL scaricabile per l'immagine della mappa del colore base.
Esempio di Oggetto Attività di Costruzione della Statuina in Vinile