Förvandla ett källfoto till en samlarbar 3D-minifigur i tegelstil i två steg:
prototyp genererar en stiliserad konceptbild från ditt inmatningsfoto, sedan
bygg omvandlar den konceptbilden till en texturerad 3D-modell. De två stegen
är länkade via input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Generera en enda konceptbild i tegelstil från källfotot. Det returnerade uppgifts-ID:t är det du skickar som input_task_id till bygg-endpointen. Se
Objektet för Brick-figurens prototypuppgift
för svarformatet.
Parametrar
Name
image_url
Type
string
Obligatorisk
Description
Källfoto för Meshy att stilisera som en tegelminifigur. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.
Det finns två sätt att tillhandahålla bilden:
Offentligt tillgänglig URL: En URL som är tillgänglig från det offentliga internet.
Data URI: En base64-kodad data URI av bilden. Exempel på en data URI: data:image/jpeg;base64,<din base64-kodade bilddata>.
Name
name
Type
string
Description
Valfritt uppgiftsnamn för visningsändamål. Max 100 tecken.
Name
remove_background
Type
boolean
standard false
Description
När den är inställd på true, returneras prototypbilden som en transparent RGBA PNG med bakgrunden borttagen, så att du kan komponera motivet på vilken bakgrund som helst.
Returnerar
result-egenskapen i svaret innehåller uppgifts-ID:t för den nyligen skapade prototypuppgiften för brick-figuren. Poll Hämta en uppgift endpointen eller prenumerera på strömmen tills uppgiften når SUCCEEDED, och skicka sedan det ID:t till bygg-endpointen som input_task_id.
Felmod
Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
Saknad parameter: image_url är obligatorisk.
Ogiltigt bildformat: Den angivna image_url är inte ett stödt format (.jpg, .jpeg, .png, .webp).
Bildmått utanför räckvidd: Bilden är för liten, överskrider den maximala filstorleken eller överskrider det maximala antalet pixlar.
Oåtkomlig URL: image_url kunde inte laddas ner (404 eller timeout).
Ogiltig Data URI: Base64-strängen är felaktig.
Innehåll flaggat: Ingångsbilden flaggades av NSFW moderation.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckliga credits för att utföra denna uppgift.
Name
403 - Forbidden
Description
Ingångsbilden flaggades för intrång i immateriella rättigheter.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.
Request
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Stage 1: generate a brick-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/brick-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>" }'
Generera den slutliga texturerade 3D-legofiguren från en lyckad prototypuppgift. Bygget kör samma bild-till-3D-pipeline som Bild till 3D, så formatet på svarobjektet och listan över utdata-URL:er matchar exakt. Se Objektet för Bygguppgift för Legofigur för svarformatet.
Parametrar
Name
input_task_id
Type
string
Obligatorisk
Description
Uppgifts-ID för en prototypuppgift skapad via denna 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 skapade genom webbappen accepteras inte — bygg-endpoint accepterar endast prototypuppgifter producerade av POST /openapi/creative-lab/brick-figure/v1/prototype och avvisar alla andra källor med 404.
Name
name
Type
string
Description
Valfritt uppgiftsnamn för visningsändamål. Max 100 tecken.
Returnerar
result-egenskapen i svaret innehåller uppgifts-id för den nyss skapade bygguppgiften för legofiguren. Poll Hämta en Uppgift endpoint eller prenumerera på strömmen tills uppgiften når SUCCEEDED, ladda sedan ner den texturerade GLB från model_urls.glb (eller OBJ + MTL-paret från model_urls.obj och model_urls.mtl om din nedströms-pipeline föredrar OBJ).
Felmod
Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
Saknad parameter: input_task_id krävs.
Ogiltig UUID: input_task_id är inte en giltig UUID.
Förälder inte lyckad: Den refererade prototypuppgiften har inte nått SUCCEEDED ännu.
Ingen kandidat: Prototypuppgiften lyckades men producerade ingen kandidatbild.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckliga credits för att utföra denna uppgift.
Name
404 - Not Found
Description
Den refererade prototypuppgiften existerar inte, tillhör en annan användare, eller skapades genom webbappen (endast API-läge prototypuppgifter kedjas till bygg).
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.
Request
POST
/openapi/creative-lab/brick-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Hämta en prototyp eller bygguppgift med ett giltigt uppgifts-id. URL-sökvägen
måste matcha uppgiftens steg — en bygguppgift hämtad genom
/prototype/:id returnerar 404, och vice versa.
Avbryt en brick-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 använda resurser). Uppgifter som redan har nått ett slutligt tillstå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
Unikt identifierare för brick-figuruppgiften som ska avbrytas.
Returnerar
Returnerar 204 No Content vid framgång med en tom kropp.
Felmod
Name
400 - Bad Request
Description
Uppgiften är redan i ett slutligt tillstånd och kan inte avbrytas.
Name
404 - Not Found
Description
Uppgiften existerar inte, tillhör en annan användare, eller dess steg matchar inte URL-sökvägen.
Strömma uppdateringar i realtid för en brickfigur-uppgift via Server-Sent Events (SSE).
URL-sökvägen måste matcha uppgiftens steg — att öppna en ström på
/prototype/:buildId/stream avger en enda event: error payload med
status_code: 404 och stänger strömmen.
Parametrar
Name
id
Type
path
Description
Unik identifierare för brickfigur-uppgiften att strömma.
Returnerar
Returnerar en ström av Brickfigur-prototyp
eller Brickfigur-bygg uppgiftsobjekt som
Server-Sent Events. För PENDING eller IN_PROGRESS uppgifter, kommer svarströmmen
endast att inkludera de nödvändiga progress och status fälten.
Hämta en paginerad lista över dina brick figur uppgifter för ett enda steg. URL-sökvägen
väljer steget — /prototype returnerar prototypuppgifter; /build
returnerar bygguppgifter. Uppgifter från det andra steget ingår inte i någon
av svaren.
Sökvägsparametrar
Name
stage
Type
path
Obligatorisk
Description
Antingen prototype eller build. Samlingen returnerar endast uppgifter
vars steg matchar URL:en — att hämta /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. Max tillåtet är 100 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.
Prototypuppgiften för Brickfigur-objektet är en arbetsenhet som Meshy håller reda på för att generera en konceptbild i tegelstil från ett källfoto. Utdata från detta steg kedjas in i byggsteget via input_task_id.
Egenskaper
Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgifts-id som implementeringsdetalj, bör du inte göra några antaganden om formatet på id.
Name
type
Type
string
Description
Typ av uppgift. Värdet är creative-lab-brick-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 en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Framsteg för uppgiften. Om uppgiften inte har startat än, kommer denna egenskap att vara 0. När uppgiften har lyckats, kommer detta att bli 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
RFC 3339-standarden.
Till exempel, fredag 1 september 2023 12:00:00 GMT representeras 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 startat än, kommer denna egenskap att vara null.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften inte har avslutats än, kommer denna egenskap att vara null.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftsresultatet löper ut, i millisekunder.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Värdet av detta fält är meningsfullt endast om uppgiftsstatus är PENDING.
Name
task_error
Type
object
Description
Felformationer för misslyckade uppgifter. Se Fel för fullständig referens till task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Förekommer när uppgiftsstatus är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED uppgifter (credits återbetalas vid misslyckande).
Name
image_urls
Type
array of strings
Description
Nedladdningsbara URL:er för konceptbildskandidater som genereras av denna prototypuppgift. För närvarande returnerar API:et alltid exakt en kandidat; fältet är en array så framtida revisioner kan visa flera kandidater utan en brytande förändring.
Exempel på Prototypuppgift för Brickfigur-objektet
Objektet för Brickfigurbyggnadsuppgift är en arbetsenhet som Meshy håller reda på för att generera en texturerad 3D-brickfigur från en lyckad prototypsuppgift. Det 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-brick-figure-build.
Name
name
Type
string
Description
Det uppgiftsnamn 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 en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Framsteg för uppgiften. Om uppgiften inte har startat än, kommer denna egenskap att vara 0. När uppgiften har lyckats, kommer detta att bli 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 går ut, 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
Felinformation för misslyckade uppgifter. Se Fel för fullständig referens till task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid misslyckande).
Name
prompt
Type
string
Description
Alltid tom för brickfigurbyggnad. Närvarande för kompatibilitet över endpoints med den delade V2ImageTo3DTaskResponse-formen som används av Bild till 3D.
Name
negative_prompt
Type
string
Description
Alltid tom för brickfigurbyggnad. Närvarande för kompatibilitet över endpoints.
Name
texture_prompt
Type
string
Description
Alltid tom för brickfigurbyggnad. Närvarande för kompatibilitet över endpoints.
Name
texture_image_url
Type
string
Description
Alltid tom för brickfigurbyggnad. Närvarande för kompatibilitet över endpoints.
Name
model_urls
Type
object
Description
Nedladdningsbara URL:er för den genererade 3D-modellen. Brickfigurbyggnaden avger en texturerad GLB plus OBJ + MTL-paret för pipelines som föredrar Wavefront OBJ. Fältformen matchar Bild till 3D model_urls objektet så att framtida formatändringar kan läggas till utan brytande förändringar.
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 OBJ:s medföljande MTL-materialfil. Para ihop med obj och posten från texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
Nedladdningsbar URL till miniatyrbilden av modelfilen.
Name
texture_urls
Type
array
Description
En array av textur-URL-objekt som genererats av denna uppgift. Innehåller för närvarande ett enda objekt med basfärgskartan.