Verander een bronfoto in een verzamelbare 3D minifiguur in baksteenstijl in twee fasen:
prototype genereert een gestileerd conceptbeeld van je invoerfoto, daarna
build verandert dat conceptbeeld in een 3D-model met texture. De twee fasen
zijn gekoppeld via input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Genereer een enkel conceptafbeelding in baksteenstijl van de bronfoto. De
geretourneerde taak-ID is wat je doorgeeft als input_task_id aan de build
endpoint. Raadpleeg
Het Brick Figuur Prototype Taak Object
voor de vorm van de respons.
Parameters
Name
image_url
Type
string
Verplicht
Description
Bronfoto voor Meshy om te stijlen als een baksteen minifiguur. We ondersteunen momenteel .jpg, .jpeg, .png, en .webp formaten.
Er zijn twee manieren om de afbeelding te verstrekken:
Openbaar toegankelijke URL: Een URL die toegankelijk is vanaf het openbare internet.
Data URI: Een base64-gecodeerde data URI van de afbeelding. Voorbeeld van een data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Optionele taaknaam voor weergavedoeleinden. Maximaal 100 tekens.
Name
remove_background
Type
boolean
standaard false
Description
Wanneer ingesteld op true, wordt de prototypeafbeelding geretourneerd als een transparante RGBA PNG met de achtergrond verwijderd, zodat je het onderwerp op elke achtergrond kunt samenstellen.
Retourneert
De result eigenschap van de respons bevat de taak id van de nieuw aangemaakte brick figuur prototype taak. Poll de Haal een Taak op endpoint of abonneer je op de stream totdat de taak SUCCEEDED bereikt, en geef die ID dan door aan de build endpoint als input_task_id.
Foutmodi
Name
400 - Bad Request
Description
Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:
Ontbrekende parameter: image_url is vereist.
Ongeldig afbeeldingsformaat: De verstrekte image_url is geen ondersteund formaat (.jpg, .jpeg, .png, .webp).
Afbeeldingsdimensies buiten bereik: De afbeelding is te klein, overschrijdt de maximale bestandsgrootte, of overschrijdt het maximale aantal pixels.
Onbereikbare URL: De image_url kon niet worden gedownload (404 of timeout).
Ongeldige Data URI: De base64-string is verkeerd gevormd.
Inhoud gemarkeerd: De invoerafbeelding werd gemarkeerd door NSFW moderation.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer je API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
403 - Forbidden
Description
De invoerafbeelding werd gemarkeerd voor schending van intellectueel eigendom.
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden.
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>" }'
Genereer het uiteindelijke 3D bakstenen figuur met textuur vanuit een geslaagde prototype taak. De bouw voert dezelfde afbeelding-naar-3D pijplijn uit als Afbeelding naar 3D, dus het formaat van het responsobject en de lijst van uitvoer-URL's komen exact overeen. Raadpleeg Het Bakstenen Figuur Bouwtaak Object voor de vorm van de respons.
Parameters
Name
input_task_id
Type
string
Verplicht
Description
De taak-ID van een prototype taak die via dezezelfde OpenAPI endpoint is aangemaakt. Het prototype moet zijn aangemaakt met dezelfde API-sleutel, moet SUCCEEDED hebben bereikt en moet exact één kandidaat-afbeelding hebben geproduceerd.
Prototype taken die via de webapp zijn aangemaakt worden niet geaccepteerd — de bouw endpoint accepteert alleen prototype taken geproduceerd door POST /openapi/creative-lab/brick-figure/v1/prototype en weigert elke andere bron met 404.
Name
name
Type
string
Description
Optionele taaknaam voor weergavedoeleinden. Maximaal 100 tekens.
Retourneert
De result eigenschap van de respons bevat de taak id van de nieuw aangemaakte bakstenen figuur bouwtaak. Poll de Haal een Taak op endpoint of abonneer je op de stream totdat de taak SUCCEEDED bereikt, en download dan de getextureerde GLB van model_urls.glb (of het OBJ + MTL paar van model_urls.obj en model_urls.mtl als je downstream pijplijn de voorkeur geeft aan OBJ).
Foutmodi
Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
Ontbrekende parameter: input_task_id is vereist.
Ongeldige UUID: De input_task_id is geen geldige UUID.
Ouder niet geslaagd: De verwezen prototype taak heeft SUCCEEDED nog niet bereikt.
Geen kandidaat: De prototype taak is geslaagd maar heeft geen kandidaat-afbeelding geproduceerd.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer je API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
404 - Not Found
Description
De verwezen prototype taak bestaat niet, behoort tot een andere gebruiker, of is aangemaakt via de webapp (alleen API-mode prototype taken schakelen over naar bouw).
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden.
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" }'
Haal een prototype- of bouwtaak op met een geldig taak id. Het URL-pad
moet overeenkomen met de fase van de taak — een bouwtaak opgehaald via
/prototype/:id retourneert 404, en vice versa.
Annuleer een brick figuur taak. Als de taak nog PENDING is, worden de credits
die bij het aanmaken zijn verbruikt, terugbetaald. Taken die al
IN_PROGRESS zijn, worden geannuleerd zonder terugbetaling (de werknemer kan al
bronnen aan het verbruiken zijn). Taken die al een eindstatus hebben bereikt
(SUCCEEDED, FAILED, CANCELED) kunnen niet worden geannuleerd.
Het URL-pad moet overeenkomen met de fase van de taak — DELETE op
/prototype/:buildId geeft 404 terug.
Padparameters
Name
id
Type
path
Description
Unieke identificatie voor de brick figuur taak om te annuleren.
Retourneert
Retourneert 204 No Content bij succes met een lege body.
Foutmodi
Name
400 - Bad Request
Description
De taak is al in een eindstatus en kan niet worden geannuleerd.
Name
404 - Not Found
Description
De taak bestaat niet, behoort tot een andere gebruiker, of de fase komt niet overeen met het URL-pad.
Stream real-time updates voor een brick figuur taak via Server-Sent Events (SSE).
Het URL-pad moet overeenkomen met de fase van de taak — het openen van een stream bij
/prototype/:buildId/stream geeft een enkele event: error payload met
status_code: 404 en sluit de stream.
Parameters
Name
id
Type
path
Description
Unieke identificatie voor de brick figuur taak om te streamen.
Retourneert
Retourneert een stream van Brick Figuur Prototype
of Brick Figuur Build taakobjecten als
Server-Sent Events. Voor PENDING of IN_PROGRESS taken zal de responsestream
alleen de noodzakelijke progress en status velden bevatten.
Haal een gepagineerde lijst op van je brick figuur taken voor een enkele fase. Het URL-pad selecteert de fase — /prototype retourneert prototype taken; /build retourneert bouwtaken. Taken van de andere fase zijn niet opgenomen in beide antwoorden.
Padparameters
Name
stage
Type
path
Verplicht
Description
Ofwel prototype of build. De collectie retourneert alleen taken
waarvan de fase overeenkomt met de URL — het ophalen van /prototype retourneert nooit
bouwtaken en vice versa.
Queryparameters
Name
page_num
Type
integer
standaard 1
Description
Paginanummer voor paginering.
Name
page_size
Type
integer
standaard 10
Description
Limiet voor paginagrootte. Maximum toegestaan is 100 items.
Name
sort_by
Type
string
standaard -created_at
Description
Veld om op te sorteren. Beschikbare waarden:
+created_at: Sorteren op creatietijd in oplopende volgorde.
-created_at: Sorteren op creatietijd in aflopende volgorde.
Het Brick Figure Prototype Task-object is een werkunit die Meshy bijhoudt om een baksteenstijl conceptafbeelding te genereren van een bronfoto. De output van deze fase wordt gekoppeld aan de bouwfase via input_task_id.
Eigenschappen
Name
id
Type
string
Description
Unieke identificatie voor de taak. Hoewel we een k-sortable UUID gebruiken voor taak-id's als implementatiedetail, moet je geen aannames maken over het formaat van de id.
Name
type
Type
string
Description
Type van de taak. De waarde is creative-lab-brick-figure-prototype.
Name
name
Type
string
Description
De taaknaam die is opgegeven toen de taak werd aangemaakt. Lege string als er geen naam is opgegeven.
Name
status
Type
string
Description
Status van de taak. Mogelijke waarden zijn een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Voortgang van de taak. Als de taak nog niet is gestart, zal deze eigenschap 0 zijn. Zodra de taak is geslaagd, wordt dit 100.
Name
created_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is aangemaakt, in milliseconden.
Een tijdstempel vertegenwoordigt het aantal milliseconden dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339 standaard. Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 PM GMT wordt weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in de Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is gestart, in milliseconden. Als de taak nog niet is gestart, zal deze eigenschap null zijn.
Name
finished_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, zal deze eigenschap null zijn.
Name
expires_at
Type
timestamp
Description
Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken.
De waarde van dit veld is alleen betekenisvol als de taakstatus PENDING is.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS of SUCCEEDED is. Geeft 0 terug voor FAILED taken (credits worden terugbetaald bij mislukking).
Name
image_urls
Type
array of strings
Description
Downloadbare URL's voor de conceptafbeelding kandidaten gegenereerd door deze prototype taak. Momenteel retourneert de API altijd precies één kandidaat; het veld is een array zodat toekomstige revisies meerdere kandidaten kunnen weergeven zonder een brekende wijziging.
Het Brick Figure Build Task-object is een werkunit die Meshy bijhoudt om een getextureerde 3D-brick-figuur te genereren vanuit een geslaagde prototype-taak. Het gebruikt dezelfde afbeelding-naar-3D-pijplijn als Afbeelding naar 3D, dus de uitvoervelden spiegelen het endpoint's task object.
Eigenschappen
Name
id
Type
string
Description
Unieke identificatie voor de taak.
Name
type
Type
string
Description
Type van de taak. De waarde is creative-lab-brick-figure-build.
Name
name
Type
string
Description
De taaknaam die werd opgegeven bij het aanmaken van de taak. Lege string als er geen naam werd opgegeven.
Name
status
Type
string
Description
Status van de taak. Mogelijke waarden zijn PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Voortgang van de taak. Als de taak nog niet is gestart, zal deze eigenschap 0 zijn. Zodra de taak is geslaagd, wordt dit 100.
Name
created_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is aangemaakt, in milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is gestart, in milliseconden.
Name
finished_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is voltooid, in milliseconden.
Name
expires_at
Type
timestamp
Description
Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken. Betekenisvol alleen wanneer de status PENDING is.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. Geeft 0 terug voor FAILED taken (credits worden terugbetaald bij een mislukking).
Name
prompt
Type
string
Description
Altijd leeg voor brick figure build. Aanwezig voor cross-endpoint compatibiliteit met de gedeelde V2ImageTo3DTaskResponse vorm gebruikt door Afbeelding naar 3D.
Name
negative_prompt
Type
string
Description
Altijd leeg voor brick figure build. Aanwezig voor cross-endpoint compatibiliteit.
Name
texture_prompt
Type
string
Description
Altijd leeg voor brick figure build. Aanwezig voor cross-endpoint compatibiliteit.
Name
texture_image_url
Type
string
Description
Altijd leeg voor brick figure build. Aanwezig voor cross-endpoint compatibiliteit.
Name
model_urls
Type
object
Description
Downloadbare URL's voor het gegenereerde 3D-model. De brick figure build levert een getextureerde GLB plus het OBJ + MTL-paar voor pijplijnen die de voorkeur geven aan Wavefront OBJ. De veldvorm komt overeen met het Afbeelding naar 3D model_urls object zodat toekomstige formaattoevoegingen zonder brekende wijziging kunnen worden toegevoegd.
Name
glb
Type
string
Description
Downloadbare URL naar het getextureerde GLB-bestand.
Name
obj
Type
string
Description
Downloadbare URL naar het Wavefront OBJ-bestand (geometrie + UV).
Name
mtl
Type
string
Description
Downloadbare URL naar het OBJ begeleidende MTL-materiaalbestand. Combineer met obj en de vermelding van texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
Downloadbare URL naar de thumbnail-afbeelding van het modelbestand.
Name
texture_urls
Type
array
Description
Een array van textuur-URL-objecten gegenereerd door deze taak. Bevat momenteel een enkel object met de basiskleurkaart.
Name
base_color
Type
string
Description
Downloadbare URL naar de basiskleurkaart afbeelding.