Creative Lab — API per 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
build 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 task di prototipo di statuina
Genera una singola immagine concettuale in stile chibi dalla foto sorgente. L'ID del
task restituito è quello che passi come input_task_id all'endpoint di build.
Consulta
L'oggetto task di prototipo di statuina
per la struttura 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.Esistono due modi per fornire l'immagine:
- URL accessibile pubblicamente: un URL accessibile da internet pubblico.
- Data URI: un Data URI dell'immagine codificato in base64. Esempio di Data URI:
data:image/jpeg;base64,<your base64-encoded image data>.
- 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 di prototipo di statuina appena creato. Esegui il polling dell'endpoint Recupera un task o iscriviti allo stream finché il task non 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è obbligatorio. - Formato immagine non valido: l'
image_urlfornito non è un formato supportato (.jpg,.jpeg,.png,.webp). - Dimensioni dell'immagine fuori intervallo: l'immagine è troppo piccola, supera la dimensione massima del file o supera il conteggio massimo di pixel.
- URL non raggiungibile: non è stato possibile scaricare l'
image_url(404 o timeout). - Data URI non valido: la stringa base64 è malformata.
- Contenuto segnalato: l'immagine di input è stata segnalata dalla moderation NSFW o della proprietà intellettuale.
- Parametro mancante:
- Name
401 - Unauthorized- Description
Autenticazione non riuscita. Controlla la tua chiave API.
- Name
402 - Payment Required- Description
Crediti insufficienti per eseguire questo task.
- Name
429 - Too Many Requests- Description
Hai superato il tuo limite di frequenza.
Request
# 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>"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Crea un'attività di build di una statuina
Genera la statuina 3D finale con texture da un'attività di prototipo riuscita. La build esegue la stessa pipeline da immagine a 3D di Immagine in 3D, quindi il formato dell'oggetto di risposta e l'elenco degli URL di output corrispondono esattamente. Consulta L'oggetto attività di build della statuina per la struttura della risposta.
Parametri
- Name
- input_task_id
- Type
- string
- Obbligatorio
- Description
L'ID attività di un'attività di prototipo creata tramite questo stesso endpoint OpenAPI. Il prototipo deve essere stato creato con la stessa chiave API, deve aver raggiunto
SUCCEEDEDe deve aver prodotto esattamente una immagine candidata.Le attività di prototipo create tramite la webapp non sono accettate: l'endpoint di build accetta solo attività di prototipo prodotte da
POST /openapi/creative-lab/figure/v1/prototypee rifiuta qualsiasi altra origine con404.
- Name
- name
- Type
- string
- Description
Nome attività facoltativo a fini di visualizzazione. Massimo 100 caratteri.
Restituisce
La proprietà result della risposta contiene l'id attività della nuova attività di build della statuina creata. Interroga l'endpoint Recupera un'attività o iscriviti allo stream finché l'attività 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 errore
- Name
400 - Bad Request- Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante:
input_task_idè obbligatorio. - UUID non valido:
input_task_idnon è un UUID valido. - Padre 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.
- Parametro mancante:
- Name
401 - Unauthorized- Description
Autenticazione non riuscita. Controlla 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 la webapp (solo le attività di prototipo in mode API possono essere concatenate alla build).
- Name
429 - Too Many Requests- Description
Hai superato il tuo limite di frequenza.
Request
# 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"
}'
Response
{
"result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Recupera un'attività statuina
Recupera un'attività di prototipo o build dato un id attività valido. Il percorso URL
deve corrispondere alla fase dell'attività: un'attività di build recuperata tramite
/prototype/:id restituisce 404, e viceversa.
Fai riferimento a L'oggetto attività prototipo della statuina e L'oggetto attività build della statuina per le forme della risposta.
Parametri
- Name
- id
- Type
- path
- Description
Identificatore univoco dell'attività statuina da recuperare.
Restituisce
La risposta contiene l'oggetto attività statuina. La forma dipende dalla fase richiesta.
Request
# 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}"
Prototype Response
{
"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=***"
]
}
Build Response
{
"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 worker potrebbe già stare
consumando risorse). Le attività che hanno già raggiunto uno stato terminale
(SUCCEEDED, FAILED, CANCELED) non possono essere annullate.
Il percorso dell'URL deve corrispondere alla fase dell'attività — DELETE su
/prototype/:buildId restituisce 404.
Parametri del percorso
- Name
- id
- Type
- path
- Description
Identificatore univoco dell'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 utente diverso oppure la sua fase non corrisponde al percorso dell'URL.
Request
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}"
Response
// Returns 204 No Content on success (empty body).
Trasmetti in streaming un'attività di statuina
Trasmetti aggiornamenti in tempo reale per un'attività di statuina tramite Server-Sent Events (SSE).
Il percorso dell'URL deve corrispondere alla fase dell'attività: l'apertura di uno stream su
/prototype/:buildId/stream emette un singolo payload event: error con
status_code: 404 e chiude lo stream.
Parametri
- Name
- id
- Type
- path
- Description
Identificatore univoco dell'attività di statuina da trasmettere in streaming.
Restituisce
Restituisce uno stream di oggetti attività Prototipo di statuina
o Build di statuina come
Server-Sent Events. Per le attività PENDING o IN_PROGRESS, lo stream della risposta
includerà solo i campi necessari progress e status.
Request
curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// 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=***"
}
]
}
Elenca le 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à prototype; /build
restituisce le attività build. Le attività dell'altra fase non sono incluse in nessuna delle due
risposte.
Parametri di 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à build 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 è
50elementi.
- Name
- sort_by
- Type
- string
- predefinito -created_at
- Description
Campo in base al quale ordinare. Valori disponibili:
+created_at: Ordina per ora di creazione in ordine crescente.-created_at: Ordina per ora di creazione in ordine decrescente.
Restituisce
Restituisce un elenco paginato dell'oggetto attività per fase — ovvero
l'oggetto attività prototype di statuina
quando si elenca /prototype oppure
l'oggetto attività build di statuina quando
si elenca /build.
Request
# 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}"
Response (List Prototype Tasks)
[
{
"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=***"
]
}
]
Oggetto attività prototipo statuina
L'oggetto attività prototipo statuina è un'unità di lavoro di cui Meshy tiene traccia per
generare un'immagine concettuale in stile chibi da una foto sorgente. L'output di
questa fase viene concatenato alla fase di build
tramite input_task_id.
Proprietà
- Name
- id
- Type
- string
- Description
Identificatore univoco per l'attività. Sebbene utilizziamo un UUID k-sortable per gli id delle attività come dettaglio implementativo, non dovresti fare alcuna supposizione sul formato dell'id.
- Name
- type
- Type
- string
- Description
Tipo dell'attività. Il valore è
creative-lab-figure-prototype.
- Name
- name
- Type
- string
- Description
Il nome dell'attività fornito al momento della creazione dell'attività. Stringa vuota se non è stato fornito alcun nome.
- Name
- status
- Type
- string
- Description
Stato dell'attività. I valori possibili sono uno tra
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, 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 nella Meshy API.
- Name
- started_at
- Type
- timestamp
- Description
timestamp di quando l'attività è stata avviata, in millisecondi. Se l'attività non è ancora iniziata, questa proprietà sarà
0.
- Name
- finished_at
- Type
- timestamp
- Description
timestamp di quando l'attività è stata completata, 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à non riuscite. Vedi Errori per il riferimento completo dell'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_PROGRESSoSUCCEEDED. Restituisce0per le attivitàFAILED(i crediti vengono rimborsati in caso di errore).
- Name
- image_urls
- Type
- array of strings
- Description
URL scaricabili per i candidati immagine concettuale generati da questa attività di prototipo. Attualmente l'API restituisce sempre esattamente un candidato; il campo è un array in modo che revisioni future possano esporre più candidati senza una modifica incompatibile.
Example Figure Prototype Task Object
{
"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=***"
]
}
Oggetto attività di creazione della statuina
L'oggetto attività di creazione della statuina è un'unità di lavoro che Meshy tiene traccia per generare una statuina 3D con texture da un'attività prototipo riuscita. Esegue la stessa pipeline Immagine in 3D usata da Immagine in 3D, quindi i campi di output rispecchiano l'oggetto attività di tale endpoint.
Proprietà
- Name
- id
- Type
- string
- Description
Identificatore univoco per l'attività.
- Name
- type
- Type
- string
- Description
Tipo dell'attività. Il valore è
creative-lab-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 tra
PENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED.
- Name
- progress
- Type
- integer
- Description
Progress dell'attività. Se l'attività non è ancora stata avviata, 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à è 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. Consulta Errori per il riferimento completo all'oggetto
task_error.
- Name
- consumed_credits
- Type
- integer
- Description
Il numero di crediti consumati da questa attività. Restituisce
0per le attivitàFAILED(i crediti vengono rimborsati in caso di errore).
- Name
- prompt
- Type
- string
- Description
Sempre vuoto per la creazione della statuina. Presente per compatibilità tra endpoint con la forma condivisa
V2ImageTo3DTaskResponseusata da Immagine in 3D.
- Name
- negative_prompt
- Type
- string
- Description
Sempre vuoto per la creazione della statuina. Presente per compatibilità tra endpoint.
- Name
- texture_prompt
- Type
- string
- Description
Sempre vuoto per la creazione della statuina. Presente per compatibilità tra endpoint.
- Name
- texture_image_url
- Type
- string
- Description
Sempre vuoto per la creazione della statuina. Presente per compatibilità tra endpoint.
- Name
- model_urls
- Type
- object
- Description
URL scaricabili per il modello 3D generato. La creazione della statuina emette un GLB con texture più la coppia OBJ + MTL per pipeline che preferiscono Wavefront OBJ. La struttura del campo corrisponde all'oggetto model_urls di Immagine in 3D, così le aggiunte future di formati possono essere inserite senza una modifica incompatibile.
- Name
glb- Type
- string
- Description
URL scaricabile per il file GLB con texture.
- Name
obj- Type
- string
- Description
URL scaricabile per il file Wavefront OBJ (geometria + UV).
- Name
mtl- Type
- string
- Description
URL scaricabile per il file di materiale MTL compagno dell'OBJ. Abbinalo a
obje alla voce datexture_urls[0].base_color.
- Name
- thumbnail_url
- Type
- string
- Description
URL scaricabile per l'immagine 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.
Example Figure Build Task Object
{
"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=***"
}
]
}