Trasforma una foto di origine in una statuina 3D da collezione con testa grande in due
fasi: prototipo genera un'immagine concettuale stilizzata dalla tua foto
di input, quindi costruisci 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 da una foto di origine. L'ID dell'attività restituito è quello che passi come input_task_id all'endpoint di creazione. Fare riferimento a
L'oggetto di attività di prototipo di statuina
per la struttura della risposta.
Parametri
Name
image_url
Type
string
Obbligatorio
Description
Foto di origine da far stilizzare a Meshy come statuina a grande testa. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.
Ci sono due modi per fornire l'immagine:
URL accessibile pubblicamente: 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à facoltativo per scopi di visualizzazione. Massimo 100 caratteri.
Restituisce
La proprietà result della risposta contiene l'ID dell'attività id del prototipo di statuina appena creata. Esegui il polling dell'Ottieni un'attività endpoint o iscriviti al stream fino a quando l'attività raggiunge SUCCEEDED, poi passa quell'ID all'endpoint di creazione come input_task_id.
Modalità di guasto
Name
400 - Bad Request
Description
La richiesta era inaccettabile. Causa 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 dai parametri: L'immagine è troppo piccola, supera la dimensione massima del file o supera il numero massimo di 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 vostra chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per svolgere questa attività.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.
Request
POST
/openapi/creative-lab/vinyl-figure/v1/prototype
# Fase 1: genera un'immagine concettuale in stile statuinacurl https://api.meshy.ai/openapi/creative-lab/vinyl-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>" }'
Response
{"result":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Genera la statuina finale 3D con texture a partire da un task di prototipo riuscito. 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 del Task di Costruzione Statuina in Vinile per la forma della risposta.
Parametri
Name
input_task_id
Type
string
Obbligatorio
Description
L'ID del task 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 task di prototipo creati tramite l'app web non sono accettati — l'endpoint di costruzione accetta solo i task di prototipo prodotti da POST /openapi/creative-lab/vinyl-figure/v1/prototype e rifiuta qualsiasi altra fonte con 404.
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 di costruzione statuina in vinile appena creato. Interroga l'Endpoint per Ottenere un Task o iscriviti allo stream finché il task non 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 di downstream preferisce OBJ).
Modalità di Fallimento
Name
400 - Bad Request
Description
La richiesta non è stata accettabile. Cause comuni:
Parametro mancante: input_task_id è richiesto.
UUID non valido: L'input_task_id non è un UUID valido.
Genitore non riuscito: Il task di prototipo di riferimento non ha ancora raggiunto SUCCEEDED.
Nessun candidato: Il task di prototipo è riuscito ma non ha prodotto immagini candidate.
Name
401 - Unauthorized
Description
Autenticazione fallita. Si prega di controllare la propria chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
404 - Not Found
Description
Il task di prototipo di riferimento non esiste, appartiene a un altro utente, o è stato creato tramite l'app web (solo i task 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/vinyl-figure/v1/build
# Fase 2: concatenazione della costruzione da un task di prototipo riuscitocurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \ -X POST \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de" }'
Recupera un compito di prototipo o build fornendo un id di compito valido. Il percorso URL
deve corrispondere alla fase del compito — un compito di build recuperato tramite
/prototype/:id restituisce 404, e viceversa.
Cancella un task di statuina in vinile. 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
impegnato a consumare risorse). I task che hanno già raggiunto uno stato terminale
(SUCCEEDED, FAILED, CANCELED) non possono essere cancellati.
Il percorso URL deve corrispondere alla fase del task — DELETE su
/prototype/:buildId restituisce 404.
Parametri del Percorso
Name
id
Type
path
Description
Identificativo univoco per il task di statuina in vinile 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 terminale e non può essere cancellato.
Name
404 - Not Found
Description
Il task non esiste, appartiene a un altro utente o la sua fase non corrisponde al percorso URL.
Flusso di aggiornamenti in tempo reale per un compito di statuina via Server-Sent Events (SSE). Il percorso URL deve corrispondere alla fase del compito — aprire un flusso a /prototype/:buildId/stream emette un unico 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 trasmettere.
Restituzioni
Restituisce un flusso di oggetti del compito Vinyl Figure Prototype o Vinyl Figure Build come Server-Sent Events. Per i compiti PENDING o IN_PROGRESS, il flusso di risposta includerà solo i campi progress e status necessari.
// Esempio di evento di errore (fase errata o compito non trovato)event: errordata: {"status_code": 404,"message": "Task not found"}// Gli esempi di eventi di messaggio illustrano il progresso del compito.// Per i compiti PENDING o IN_PROGRESS, il flusso di risposta non includerà tutti i campi.event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","type": "creative-lab-vinyl-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1752969700000,"started_at": 1752969710000,"finished_at": 1752969735000,"expires_at": 1753228935000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***" } ]}
Recupera un elenco paginato delle tue attività di statuine in vinile per un singolo stadio.
Il percorso URL seleziona lo stadio — /prototype restituisce le attività di prototipo;
/build restituisce le attività di costruzione. Le attività dell'altro stadio non sono incluse
in nessuna delle risposte.
Parametri del Percorso
Name
stage
Type
path
Obbligatorio
Description
O prototype o build. La collezione restituisce solo le attività
il cui stadio corrisponde all'URL — recuperare /prototype non restituirà mai
attività di costruzione e viceversa.
Parametri di Ricerca
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 è di 50 elementi.
Name
sort_by
Type
string
predefinito -created_at
Description
Campo su cui ordinare. Valori disponibili:
+created_at: Ordina per tempo di creazione in ordine crescente.
-created_at: Ordina per tempo di creazione in ordine decrescente.
# Elenca le attività di prototipocurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"# Elenca le attività di costruzionecurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"
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 il compito. Anche se utilizziamo un UUID k-sortable per gli id dei compiti come dettaglio di implementazione, non dovresti fare alcuna ipotesi sul formato dell'id.
Name
type
Type
string
Description
Tipo di compito. Il valore è creative-lab-vinyl-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 dei seguenti: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Avanzamento del compito. Se il compito non è ancora iniziato, questa proprietà sarà 0. Una volta che il compito sarà 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 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 è iniziato, in millisecondi. Se il compito non è ancora iniziato, questa proprietà sarà 0.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il compito è terminato, in millisecondi. Se il compito non è ancora terminato, questa proprietà sarà 0.
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 degli errori 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 all'immagine concettuale generati da questo compito prototipo. Attualmente l'API restituisce sempre esattamente un candidato; il campo è un array, in modo che le future revisioni possano introdurre più candidati senza una modifica che interrompa la compatibilità.
L'oggetto Compito di Costruzione della Statuina in Vinile è un'unità di lavoro che Meshy tiene traccia
per generare una statuina in vinile 3D con texture a partire da un compito prototipo riuscito.
Utilizza la stessa pipeline di immagine-in-3D usata da Immagine in 3D,
quindi i campi di output rispecchiano il task object di quell'endpoint.
Proprietà
Name
id
Type
string
Description
Identificatore univoco per il compito.
Name
type
Type
string
Description
Tipo del compito. Il valore è creative-lab-vinyl-figure-build.
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.
Name
started_at
Type
timestamp
Description
Timestamp di quando il compito è iniziato, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il compito è stato completato, in millisecondi.
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. Significativo solo quando lo stato è PENDING.
Name
task_error
Type
object
Description
Dettagli degli errori 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. Restituisce 0 per i compiti 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 il Wavefront OBJ. La forma del campo corrisponde all'oggetto Immagine in 3D model_urls in modo che le aggiunte di formati futuri si incastrino 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 accompagnatore dell'OBJ. Da abbinare 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 texture generati da questo compito. 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.
Esempio di Oggetto Compito costruzione Statuina in Vinile