Förvandla ett källfoto till en samlarbar 3D-figur i chibi-stil i två steg:
prototype genererar en stiliserad konceptbild från ditt inmatade foto, och därefter
build förvandlar konceptbilden till en texturerad 3D-modell. De två stegen
länkas via input_task_id.
Generera en enda konceptbild i chibi-stil från källfotot. Det
returnerade uppgifts-ID:t är det du skickar som input_task_id till build-
endpointen. Se
Objektet för figurprototypuppgift
för svarsstrukturen.
Parametrar
Name
image_url
Type
string
Obligatorisk
Description
Källfoto som Meshy ska stilisera som en chibi-figur. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.
Det finns två sätt att tillhandahålla bilden:
Offentligt åtkomlig URL: En URL som är åtkomlig från det offentliga internet.
Data URI: En base64-kodad Data URI för bilden. Exempel på en Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Valfritt uppgiftsnamn för visningsändamål. Högst 100 tecken.
Returnerar
Egenskapen result i svaret innehåller uppgiftens id för den nyligen skapade figurprototypuppgiften. Polla endpointen Hämta en uppgift eller prenumerera på strömmen tills uppgiften når SUCCEEDED, och skicka sedan detta ID till build-endpointen som input_task_id.
Fellägen
Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
Saknad parameter: image_url krävs.
Ogiltigt bildformat: Den angivna image_url har inte ett format som stöds (.jpg, .jpeg, .png, .webp).
Bilddimensioner utanför intervallet: Bilden är för liten, överskrider den maximala filstorleken eller överskrider det maximala pixelantalet.
Oåtkomlig URL: image_url kunde inte laddas ned (404 eller timeout).
Ogiltig Data URI: Base64-strängen är felaktigt utformad.
Flaggat innehåll: Indatabilden flaggades av NSFW- eller immaterialrätts-moderation.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med credits för att utföra den här uppgiften.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.
Request
POST
/openapi/creative-lab/figure/v1/prototype
# Stage 1: generate a chibi-style concept imagecurl 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"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Generera den slutliga texturerade 3D-figuren från en lyckad prototypuppgift.
Bygget kör samma bild-till-3D-pipeline som
Bild till 3D, så svarsobjektets format och
listan över utdata-URL:er matchar exakt. Se
Objektet för figurbygguppgift för
svarsstrukturen.
Parametrar
Name
input_task_id
Type
string
Obligatorisk
Description
Uppgifts-ID:t för en prototypuppgift som skapats via samma OpenAPI-endpoint. Prototypen måste ha skapats med samma API-nyckel, måste ha nått SUCCEEDED och måste ha producerat exakt en kandidatbild.
Prototypuppgifter som skapats via webbappen accepteras inte — bygg-endpointen accepterar endast prototypuppgifter som producerats av POST /openapi/creative-lab/figure/v1/prototype och avvisar alla andra källor med 404.
Name
name
Type
string
Description
Valfritt uppgiftsnamn för visningsändamål. Högst 100 tecken.
Returnerar
Egenskapen result i svaret innehåller uppgifts-id för den nyligen skapade figurbygguppgiften. Polla endpointen Hämta en uppgift eller prenumerera på strömmen tills uppgiften når SUCCEEDED, ladda sedan ned den texturerade GLB-filen från model_urls.glb (eller OBJ + MTL-paret från model_urls.obj och model_urls.mtl om din efterföljande pipeline föredrar OBJ).
Fellägen
Name
400 - Bad Request
Description
Begäran var inte acceptabel. Vanliga orsaker:
Saknad parameter: input_task_id krävs.
Ogiltig UUID: input_task_id är inte en giltig UUID.
Överordnad inte lyckad: Den refererade prototypuppgiften har ännu inte nått SUCCEEDED.
Ingen kandidat: Prototypuppgiften lyckades men producerade ingen kandidatbild.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med credits för att utföra denna uppgift.
Name
404 - Not Found
Description
Den refererade prototypuppgiften finns inte, tillhör en annan användare eller skapades via webbappen (endast prototypuppgifter i API-mode kan kedjas till build).
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.
Request
POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurl 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"}
Build example
The build task turns the selected prototype image into a downloadable textured 3D model.
Hämta en prototyp- eller build-uppgift med ett giltigt uppgifts-id. URL-sökvägen
måste matcha uppgiftens fas — en build-uppgift som hämtas via
/prototype/:id returnerar 404, och vice versa.
Avbryt en figuruppgift. Om uppgiften fortfarande är PENDING återbetalas de credits
som förbrukades vid skapandet. Uppgifter som redan är
IN_PROGRESS avbryts utan återbetalning (arbetaren kan redan hålla på att
förbruka resurser). Uppgifter som redan har nått ett sluttillstånd
(SUCCEEDED, FAILED, CANCELED) kan inte avbrytas.
URL-sökvägen måste matcha uppgiftens steg — DELETE på
/prototype/:buildId returnerar 404.
Sökvägsparametrar
Name
id
Type
path
Description
Unik identifierare för figuruppgiften som ska avbrytas.
Returnerar
Returnerar 204 No Content vid lyckat resultat med en tom kropp.
Fellägen
Name
400 - Bad Request
Description
Uppgiften är redan i ett sluttillstånd och kan inte avbrytas.
Name
404 - Not Found
Description
Uppgiften finns inte, tillhör en annan användare eller dess steg matchar inte URL-sökvägen.
Strömma realtidsuppdateringar för en figuruppgift via Server-Sent Events (SSE).
URL-sökvägen måste matcha uppgiftens steg — att öppna en ström vid
/prototype/:buildId/stream skickar ut en enda event: error payload med
status_code: 404 och stänger strömmen.
Parametrar
Name
id
Type
path
Description
Unik identifierare för figuruppgiften som ska strömmas.
Returnerar
Returnerar en ström med uppgiftsobjekt för figurprototyp
eller figurbygge som
Server-Sent Events. För uppgifter med PENDING eller IN_PROGRESS kommer
svarsströmmen endast att inkludera de nödvändiga fälten progress och status.
Hämta en paginerad lista över dina figuruppgifter för ett enskilt steg. URL-
sökvägen väljer steget — /prototype returnerar prototypuppgifter; /build
returnerar bygguppgifter. Uppgifter från det andra steget inkluderas inte i något
svar.
Sökvägsparametrar
Name
stage
Type
path
Obligatorisk
Description
Antingen prototype eller build. Samlingen returnerar endast uppgifter
vars steg matchar URL:en — hämtning av /prototype returnerar aldrig
bygguppgifter och vice versa.
Frågeparametrar
Name
page_num
Type
integer
standard 1
Description
Sidnummer för paginering.
Name
page_size
Type
integer
standard 10
Description
Sidstorleksgräns. Maximalt tillåtet är 50 objekt.
Name
sort_by
Type
string
standard -created_at
Description
Fält att sortera efter. Tillgängliga värden:
+created_at: Sortera efter skapandetid i stigande ordning.
-created_at: Sortera efter skapandetid i fallande ordning.
Uppgiftsobjektet för figurprototyp är en arbetsenhet som Meshy håller reda på för att
generera en konceptbild i chibi-stil från ett källfoto. Utdata från
detta steg kopplas vidare till byggsteget
via input_task_id.
Egenskaper
Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder ett k-sorterbart UUID för uppgifts-id:n som implementeringsdetalj, bör du inte göra några antaganden om id:ts format.
Name
type
Type
string
Description
Typ av uppgift. Värdet är creative-lab-figure-prototype.
Name
name
Type
string
Description
Uppgiftsnamnet som angavs när uppgiften skapades. Tom sträng om inget namn angavs.
Name
status
Type
string
Description
Status för uppgiften. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Uppgiftens progress. Om uppgiften inte har startats ännu är den här egenskapen 0. När uppgiften har slutförts framgångsrikt blir detta 100.
Name
created_at
Type
timestamp
Description
Tidsstämpel för när uppgiften skapades, i millisekunder.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan 1 januari 1970 UTC, enligt
standarden RFC 3339.
Till exempel representeras fredag 1 september 2023 12:00:00 GMT som 1693569600000. Detta gäller
för alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startats ännu är den här egenskapen 0.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften slutfördes, i millisekunder. Om uppgiften inte har slutförts ännu är den här egenskapen 0.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftsresultatet upphör att gälla, i millisekunder.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Värdet för det här fältet är endast meningsfullt om uppgiftens status är PENDING.
Name
task_error
Type
object
Description
Feldetaljer för misslyckade uppgifter. Se Fel för fullständig referens för objektet task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukas av den här uppgiften. Finns när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).
Name
image_urls
Type
array of strings
Description
Nedladdningsbara URL:er för de konceptbildskandidater som genereras av den här prototypuppgiften. För närvarande returnerar API:et alltid exakt en kandidat; fältet är en array så att framtida revisioner kan visa flera kandidater utan en brytande ändring.
Objektet för figurbygguppgift är en arbetsenhet som Meshy håller reda på för att
generera en texturerad 3D-figur från en lyckad prototypuppgift. Den
kör samma bild-till-3D-pipeline som används av Bild till 3D,
så utdatafälten speglar den endpointens uppgiftsobjekt.
Egenskaper
Name
id
Type
string
Description
Unik identifierare för uppgiften.
Name
type
Type
string
Description
Typ av uppgift. Värdet är creative-lab-figure-build.
Name
name
Type
string
Description
Uppgiftsnamnet som angavs när uppgiften skapades. Tom sträng om inget namn angavs.
Name
status
Type
string
Description
Uppgiftens status. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Uppgiftens progress. Om uppgiften inte har startats ännu kommer den här egenskapen att vara 0. När uppgiften har slutförts blir detta 100.
Name
created_at
Type
timestamp
Description
Tidsstämpel för när uppgiften skapades, i millisekunder.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften avslutades, i millisekunder.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftsresultatet upphör att gälla, i millisekunder.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter. Meningsfullt endast när status är PENDING.
Name
task_error
Type
object
Description
Feldetaljer för misslyckade uppgifter. Se Fel för fullständig objektreferens för task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av den här uppgiften. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).
Name
prompt
Type
string
Description
Alltid tomt för figurbygge. Finns för kompatibilitet mellan endpoint med den delade V2ImageTo3DTaskResponse-formen som används av Bild till 3D.
Name
negative_prompt
Type
string
Description
Alltid tomt för figurbygge. Finns för kompatibilitet mellan endpoint.
Name
texture_prompt
Type
string
Description
Alltid tomt för figurbygge. Finns för kompatibilitet mellan endpoint.
Name
texture_image_url
Type
string
Description
Alltid tomt för figurbygge. Finns för kompatibilitet mellan endpoint.
Name
model_urls
Type
object
Description
Nedladdningsbara URL:er för den genererade 3D-modellen. Figurbygget genererar en texturerad GLB samt paret OBJ + MTL för pipelines som föredrar Wavefront OBJ. Fältformen matchar objektet Bild till 3D model_urls så att framtida formattillägg kan läggas till utan en brytande ändring.
Name
glb
Type
string
Description
Nedladdningsbar URL till den texturerade GLB-filen.
Name
obj
Type
string
Description
Nedladdningsbar URL till Wavefront OBJ-filen (geometri + UV).
Name
mtl
Type
string
Description
Nedladdningsbar URL till MTL-materialfilen som hör till OBJ. Para ihop med obj och posten från texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
Nedladdningsbar URL till miniatyrbilden för modellfilen.
Name
texture_urls
Type
array
Description
En array med textur-URL-objekt som genererats av den här uppgiften. Innehåller för närvarande ett enda objekt med basfärgskartan.
Name
base_color
Type
string
Description
Nedladdningsbar URL till bilden för basfärgskartan.