Creative Lab — API Statuina
Trasforma una foto sorgente in una statuina 3D da collezione in stile chibi 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/figure/v1/prototypePOST /openapi/creative-lab/figure/v1/build
Crea un'attività di prototipo di statuina
Genera un'immagine concettuale in stile chibi 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à di prototipo di statuina
per la forma della risposta.
Parametri
- Name
- image_url
- Type
- string
- Obbligatorio
- Description
Foto sorgente che Meshy deve stilizzare come statuina chibi. Attualmente supportiamo i formati
.jpg,.jpeg,.pnge.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 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à id della nuova attività di prototipo di statuina creata. Interroga l'endpoint Ottieni un'attività o iscriviti al stream fino a quando l'attività raggiunge SUCCEEDED, quindi passa quell'ID all'endpoint di build come input_task_id.
Modalità di errore
- Name
400 - Bad Request- Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante:
image_urlè richiesto. - Formato immagine non valido: L'
image_urlfornito non è 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_urlnon 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.
- Parametro mancante:
- 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
# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/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>"
}'
Risposta
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Crea un Task di Costruzione Statuina
Genera la statuina 3D finale con texture da un task 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. Fare riferimento a L'oggetto Task di Costruzione Statuina per la struttura 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
SUCCEEDEDe deve aver prodotto esattamente un'immagine candidata.I task prototipo creati tramite l'app web non sono accettati — l'endpoint di costruzione accetta solo task prototipo prodotti da
POST /openapi/creative-lab/figure/v1/prototypee rifiuta qualsiasi altra fonte con404.
- Name
- name
- Type
- string
- Description
Nome del task opzionale per scopi di visualizzazione. Massimo 100 caratteri.
Restituisce
La proprietà result della risposta contiene l'id del task del nuovo task di costruzione statuina creato. Interroga l'endpoint Recupera un Task o iscriviti al stream fino a quando 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 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_idnon è un UUID valido. - Genitore non riuscito: Il task prototipo di riferimento non ha ancora raggiunto
SUCCEEDED. - Nessun candidato: Il task prototipo è riuscito ma non ha prodotto alcuna immagine candidata.
- Parametro mancante:
- Name
401 - Unauthorized- Description
Autenticazione fallita. Si prega di controllare la tua chiave API.
- Name
402 - Payment Required- Description
Crediti insufficienti per eseguire questo task.
- Name
404 - Not Found- Description
Il task prototipo di riferimento non esiste, appartiene a un altro utente o è stato creato tramite l'app web (solo i task prototipo in modalità API si concatenano nella costruzione).
- Name
429 - Too Many Requests- Description
Hai superato il tuo limite di frequenza.
Richiesta
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/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"
}'
Risposta
{
"result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Recupera un'attività di Statuina
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.
Consulta L'oggetto Attività di Prototipo di Statuina e L'oggetto Attività di Costruzione di Statuina per le forme di risposta.
Parametri
- Name
- id
- Type
- path
- Description
Identificatore univoco per l'attività di statuina da recuperare.
Restituisce
La risposta contiene l'oggetto attività di statuina. La forma dipende da quale fase è stata richiesta.
Richiesta
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Risposta Prototipo
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
Risposta Costruzione
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"prompt": "",
"negative_prompt": "",
"texture_prompt": "",
"texture_image_url": "",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
}
]
}
Elimina un'attività di statuina
Annulla un'attività di statuina. 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 utilizzo delle 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 da annullare.
Restituisce
Restituisce 204 No Content in caso di successo con un corpo vuoto.
Modalità di errore
- 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 altro utente o la sua fase non corrisponde al percorso URL.
Richiesta
curl --request DELETE \
--url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Risposta
// Returns 204 No Content on success (empty body).
Trasmetti un'attività di statuina
Trasmetti aggiornamenti in tempo reale per un'attività di statuina 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 da trasmettere.
Restituisce
Restituisce un flusso di oggetti attività Prototype di statuina
o Build di statuina come Server-Sent Events. Per le attività PENDING o IN_PROGRESS, il flusso di risposta includerà solo i campi necessari progress e status.
Richiesta
curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Flusso di Risposta
// Error event example (wrong stage or task not found)
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"task_error": null,
"consumed_credits": 20,
"prompt": "",
"negative_prompt": "",
"texture_prompt": "",
"texture_image_url": "",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
}
]
}
Elenco delle attività di statuina
Recupera un elenco paginato delle tue attività di statuina 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 due risposte.
Parametri del percorso
- Name
- stage
- Type
- path
- Obbligatorio
- Description
O
prototypeobuild. La raccolta restituisce solo le attività la cui fase corrisponde all'URL — il recupero di/prototypenon 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 è di
50elementi.
- 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.
Restituisce
Restituisce un elenco paginato dell'oggetto attività per fase — o
l'oggetto attività di prototipo di statuina
quando si elenca /prototype o
l'oggetto attività di costruzione di statuina quando
si elenca /build.
Richiesta
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Risposta (Elenco delle attività di prototipo)
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
]
L'oggetto Task del Prototipo di Statuina
L'oggetto Task del Prototipo di Statuina è un'unità di lavoro che Meshy tiene traccia per generare un'immagine concettuale in stile chibi 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 task. Anche se utilizziamo un UUID k-sortable per gli id dei task come dettaglio di implementazione, non dovresti fare alcuna ipotesi sul formato dell'id.
- Name
- type
- Type
- string
- Description
Tipo di task. Il valore è
creative-lab-figure-prototype.
- Name
- name
- Type
- string
- Description
Il nome del task fornito quando il task è stato creato. Stringa vuota se non è stato fornito alcun nome.
- Name
- status
- Type
- string
- Description
Stato del task. I valori possibili sono uno di
PENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED.
- Name
- progress
- Type
- integer
- Description
Avanzamento del task. Se il task non è ancora iniziato, questa proprietà sarà
0. Una volta che il task è riuscito, diventerà100.
- Name
- created_at
- Type
- timestamp
- Description
Timestamp di quando il task è 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 nella Meshy API.
- Name
- started_at
- Type
- timestamp
- Description
Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora iniziato, questa proprietà sarà
0.
- Name
- finished_at
- Type
- timestamp
- Description
Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora completato, questa proprietà sarà
0.
- Name
- expires_at
- Type
- timestamp
- Description
Timestamp di quando il risultato del task scade, in millisecondi.
- Name
- preceding_tasks
- Type
- integer
- Description
Il conteggio dei task precedenti.
Il valore di questo campo è significativo solo se lo stato del task è
PENDING.
- Name
- task_error
- Type
- object
- Description
Dettagli dell'errore per i task falliti. Vedi Errori per il riferimento completo all'oggetto
task_error.
- Name
- consumed_credits
- Type
- integer
- Description
Il numero di crediti consumati da questo task. Presente quando lo stato del task è
PENDING,IN_PROGRESS, oSUCCEEDED. Restituisce0per i taskFAILED(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 task prototipo. Attualmente l'API restituisce sempre esattamente un candidato; il campo è un array in modo che le future revisioni possano presentare più candidati senza una modifica dirompente.
Esempio di Oggetto Task del Prototipo di Statuina
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
L'oggetto Task di Costruzione della Statuina
L'oggetto Task di Costruzione della Statuina è un'unità di lavoro che Meshy tiene traccia per generare una statuina 3D texturizzata da un task prototipo riuscito. Utilizza la stessa pipeline immagine-in-3D usata da Immagine in 3D, quindi i campi di output rispecchiano l'oggetto task di quell'endpoint.
Proprietà
- Name
- id
- Type
- string
- Description
Identificatore univoco per il task.
- Name
- type
- Type
- string
- Description
Tipo di task. Il valore è
creative-lab-figure-build.
- Name
- name
- Type
- string
- Description
Il nome del task fornito quando il task è stato creato. Stringa vuota se non è stato fornito alcun nome.
- Name
- status
- Type
- string
- Description
Stato del task. I valori possibili sono uno di
PENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED.
- Name
- progress
- Type
- integer
- Description
Avanzamento del task. Se il task non è ancora iniziato, questa proprietà sarà
0. Una volta che il task è riuscito, diventerà100.
- Name
- created_at
- Type
- timestamp
- Description
Timestamp di quando il task è stato creato, in millisecondi.
- Name
- started_at
- Type
- timestamp
- Description
Timestamp di quando il task è stato avviato, in millisecondi.
- Name
- finished_at
- Type
- timestamp
- Description
Timestamp di quando il task è stato completato, in millisecondi.
- Name
- expires_at
- Type
- timestamp
- Description
Timestamp di quando il risultato del task scade, in millisecondi.
- Name
- preceding_tasks
- Type
- integer
- Description
Il conteggio dei task precedenti. Significativo solo quando lo stato è
PENDING.
- Name
- task_error
- Type
- object
- Description
Dettagli dell'errore per i task falliti. Vedi Errori per il riferimento completo all'oggetto
task_error.
- Name
- consumed_credits
- Type
- integer
- Description
Il numero di crediti consumati da questo task. Restituisce
0per i taskFAILED(i crediti vengono rimborsati in caso di fallimento).
- Name
- prompt
- Type
- string
- Description
Sempre vuoto per la costruzione della statuina. Presente per la compatibilità cross-endpoint con la forma condivisa
V2ImageTo3DTaskResponseusata da Immagine in 3D.
- Name
- negative_prompt
- Type
- string
- Description
Sempre vuoto per la costruzione della statuina. Presente per la compatibilità cross-endpoint.
- Name
- texture_prompt
- Type
- string
- Description
Sempre vuoto per la costruzione della statuina. Presente per la compatibilità cross-endpoint.
- Name
- texture_image_url
- Type
- string
- Description
Sempre vuoto per la costruzione della statuina. Presente per la compatibilità cross-endpoint.
- Name
- model_urls
- Type
- object
- Description
URL scaricabili per il modello 3D generato. La costruzione della statuina 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 aggiunte future di formati 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
obje l'elemento datexture_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 questo task. 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 Task di Costruzione della Statuina
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"prompt": "",
"negative_prompt": "",
"texture_prompt": "",
"texture_image_url": "",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
}
]
}