Verander een bronfoto in twee fasen in een verzamelbaar 3D-minifiguurtje in bakstenenstijl:
prototype genereert een gestileerde conceptafbeelding op basis van je invoerfoto, en vervolgens
zet build die conceptafbeelding om in een 3D-model met textures. De twee fasen
zijn met elkaar verbonden via input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Genereer een enkele conceptafbeelding in bakstenen-stijl vanuit de bronfoto. De
geretourneerde taak-ID is wat u doorgeeft als input_task_id aan de build-
endpoint. Raadpleeg
The Brick Figure Prototype Task Object
voor de vorm van de response.
Parameters
Name
image_url
Type
string
Verplicht
Description
Bronfoto die Meshy moet stileren als een bakstenen-minifiguur. We ondersteunen momenteel de formaten .jpg, .jpeg, .png en .webp.
Er zijn twee manieren om de afbeelding aan te leveren:
Publiek 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 prototype-afbeelding geretourneerd als een transparante RGBA-PNG met de achtergrond verwijderd, zodat u het onderwerp op elke gewenste achtergrond kunt plaatsen.
Retourwaarden
De result-eigenschap van de response bevat de taak-id van de nieuw aangemaakte brick figure prototype-taak. Poll de Get a Task-endpoint of abonneer u op de stream totdat de taak SUCCEEDED bereikt, en geef die ID vervolgens 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 verplicht.
Ongeldig afbeeldingsformaat: de opgegeven image_url heeft geen ondersteund formaat (.jpg, .jpeg, .png, .webp).
Afbeeldingsafmetingen 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 onjuist geformatteerd.
Content gemarkeerd: de invoerafbeelding is gemarkeerd door NSFW-moderation.
Name
401 - Unauthorized
Description
Authenticatie is mislukt. Controleer uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
403 - Forbidden
Description
De invoerafbeelding is gemarkeerd wegens schending van intellectueel eigendom.
Name
429 - Too Many Requests
Description
U heeft uw 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 getextureerde 3D brick figure vanuit een geslaagde prototype-taak. De build doorloopt dezelfde afbeelding-naar-3D-pipeline als
Afbeelding naar 3D, dus de vorm van het response-object en de
lijst met output-URL's komen exact overeen. Raadpleeg
Het Brick Figure Build Task Object voor de
vorm van de response.
Parameters
Name
input_task_id
Type
string
Verplicht
Description
Het task ID van een prototype-taak die via dezelfde OpenAPI-endpoint is aangemaakt. Het prototype moet zijn aangemaakt met dezelfde API-sleutel, moet SUCCEEDED hebben bereikt, en moet precies één kandidaatafbeelding hebben geproduceerd.
Prototype-taken die via de webapp zijn aangemaakt worden niet geaccepteerd — de build-endpoint accepteert alleen prototype-taken die zijn 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.
Retourwaarden
De result-eigenschap van de response bevat het task-id van de nieuw aangemaakte brick figure build-taak. Poll de Get a Task-endpoint of abonneer je op de stream totdat de taak SUCCEEDED bereikt, en download vervolgens de getextureerde GLB via model_urls.glb (of het OBJ + MTL-paar via model_urls.obj en model_urls.mtl als jouw downstream-pipeline liever OBJ gebruikt).
Foutmodi
Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
Ontbrekende parameter: input_task_id is verplicht.
Ongeldige UUID: De input_task_id is geen geldige UUID.
Bovenliggende taak niet geslaagd: De referentiële prototype-taak heeft SUCCEEDED nog niet bereikt.
Geen kandidaat: De prototype-taak is geslaagd, maar heeft geen kandidaatafbeelding geproduceerd.
Name
401 - Unauthorized
Description
Authenticatie is mislukt. Controleer je API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
404 - Not Found
Description
De referentiële prototype-taak bestaat niet, behoort tot een andere gebruiker, of is aangemaakt via de webapp (alleen prototype-taken in API-mode kunnen worden doorgeschakeld naar build).
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 buildtaak op aan de hand van een geldige taak-id. Het URL-pad
moet overeenkomen met de fase van de taak — een buildtaak die wordt opgehaald via
/prototype/:id retourneert 404, en omgekeerd.
Annuleer een brick figure-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 worker
kan mogelijk al bronnen verbruiken). 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 identifier voor de brick figure-taak die moet worden geannuleerd.
Retourwaarden
Geeft 204 No Content terug bij succes met een lege body.
Faalscenario's
Name
400 - Bad Request
Description
De taak bevindt zich al in een eindstatus en kan niet worden geannuleerd.
Name
404 - Not Found
Description
De taak bestaat niet, behoort toe aan een andere gebruiker, of de fase ervan komt niet overeen met het URL-pad.
Stream realtime updates voor een brick figure-taak via Server-Sent Events (SSE).
Het URL-pad moet overeenkomen met de fase van de taak — het openen van een stream op
/prototype/:buildId/stream geeft een enkele event: error-payload met
status_code: 404 en sluit de stream.
Parameters
Name
id
Type
path
Description
Unieke identifier voor de brick figure-taak die gestreamd moet worden.
Returns
Retourneert een stream van Brick Figure Prototype-
of Brick Figure Build-taakobjecten als
Server-Sent Events. Elk frame bevat het volledige taakobject voor de fase — dezelfde vorm die het
Get-endpoint retourneert — dus zolang de taak PENDING of IN_PROGRESS is, zijn de
outputvelden simpelweg nog niet ingevuld (null, [] of {}) en is
finished_at gelijk aan null.
Haal een gepagineerde lijst op van uw brick figure-taken voor één fase. Het URL-pad
bepaalt de fase — /prototype retourneert prototype-taken; /build
retourneert build-taken. Taken van de andere fase worden niet in beide
antwoorden opgenomen.
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
build-taken en omgekeerd.
Queryparameters
Name
page_num
Type
integer
standaard 1
Description
Paginanummer voor paginering.
Name
page_size
Type
integer
standaard 10
Description
Paginagroottelimiet. Maximaal toegestaan is 100 items.
Name
sort_by
Type
string
standaard -created_at
Description
Veld om op te sorteren. Beschikbare waarden:
+created_at: Sorteer op aanmaaktijd in oplopende volgorde.
-created_at: Sorteer op aanmaaktijd in aflopende volgorde.
Het Brick Figure Prototype-taakobject is een werkeenheid die Meshy bijhoudt om
een conceptafbeelding in bakstenen-stijl te genereren uit een bronfoto. De uitvoer van
deze fase wordt doorgeschakeld naar de build-fase
via input_task_id.
Eigenschappen
Name
id
Type
string
Description
Unieke identifier voor de taak. Hoewel we een k-sorteerbare UUID gebruiken voor taak-id's als implementatiedetail, moet je geen aannames doen 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 bij het aanmaken van de taak. 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, is deze eigenschap 0. 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 geeft het aantal milliseconden weer dat is verstreken sinds 1 januari 1970 UTC, volgens
de RFC 3339-standaard.
Vrijdag 1 september 2023 12:00:00 PM GMT wordt bijvoorbeeld weergegeven als 1693569600000. Dit geldt
voor alle tijdstempels in Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap null.
Name
finished_at
Type
timestamp
Description
Tijdstempel van wanneer de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap null.
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 relevant als de taakstatus PENDING is.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.
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. Retourneert 0 voor FAILED-taken (credits worden terugbetaald bij mislukking).
Name
image_urls
Type
array of strings
Description
Downloadbare URL's voor de conceptafbeelding-kandidaten die door deze prototype-taak zijn gegenereerd. Momenteel retourneert de API altijd precies één kandidaat; het veld is een array zodat toekomstige revisies meerdere kandidaten kunnen tonen zonder een breaking change.
Het Brick Figure Build Task-object is een werkeenheid die Meshy bijhoudt om
een getextureerde 3D bakstenen figuur te genereren op basis van een geslaagde prototypetaak. Het
draait dezelfde image-to-3D-pipeline die wordt gebruikt door Afbeelding naar 3D,
dus de outputvelden komen overeen met het task-object van die endpoint.
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 is opgegeven bij het aanmaken van de taak. 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, is deze eigenschap 0. 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 voorafgaande taken. Alleen relevant wanneer de status PENDING is.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. Retourneert 0 voor FAILED-taken (credits worden terugbetaald bij mislukking).
Name
prompt
Type
string
Description
Altijd leeg voor brick figure build. Aanwezig voor cross-endpoint-compatibiliteit met de gedeelde V2ImageTo3DTaskResponse-vorm die wordt 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 pipelines die de voorkeur geven aan Wavefront OBJ. De vorm van dit veld komt overeen met het Image to 3D model_urls-object, zodat toekomstige formaattoevoegingen zonder breaking change kunnen worden ingepast.
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 bijbehorende OBJ MTL-materiaalbestand. Combineer met obj en het item uit 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 die door deze taak zijn gegenereerd. Bevat momenteel één object met de basiskleurenkaart.
Name
base_color
Type
string
Description
Downloadbare URL naar de afbeelding van de basiskleurenkaart.