Verander een bronfoto in een big-head vinyl verzamelbare 3D figuur in twee
fasen: prototype genereert een gestileerd conceptbeeld van je invoerfoto,
vervolgens verandert bouw dat conceptbeeld in een getextureerd 3D model.
De twee fasen zijn gekoppeld via input_task_id.
POST /openapi/creative-lab/vinyl-figure/v1/prototype
Genereer een enkel conceptafbeelding in vinyl-figuur-stijl van de bronfoto. De geretourneerde taak-ID is wat je doorgeeft als input_task_id aan de build endpoint. Raadpleeg Het Vinyl 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 groot-hoofd vinyl figuur. We ondersteunen momenteel de formaten .jpg, .jpeg, .png, en .webp.
Er zijn twee manieren om de afbeelding te leveren:
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,<je base64-gecodeerde afbeeldingsdata>.
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 je het onderwerp op elke achtergrond kunt samenstellen.
Retourneert
De result eigenschap van de respons bevat de taak id van de nieuw aangemaakte vinyl 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 onacceptabel. Veelvoorkomende oorzaken:
Ontbrekende parameter: image_url is vereist.
Ongeldig afbeeldingsformaat: De opgegeven 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 onjuist.
Inhoud gemarkeerd: De invoerafbeelding werd gemarkeerd door NSFW of intellectuele eigendom 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
429 - Too Many Requests
Description
Je hebt je rate limit overschreden.
Request
POST
/openapi/creative-lab/vinyl-figure/v1/prototype
# Stage 1: generate a vinyl-figure-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-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>" }'
Response
{"result":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Prototype voorbeeld
Begin met een bronfoto, genereer vervolgens de prototype-afbeelding die door de bouwfase wordt gebruikt.
Genereer het uiteindelijke 3D vinyl figuur met textuur vanuit een geslaagde prototype taak. De bouw gebruikt dezelfde afbeelding-naar-3D pijplijn als Afbeelding naar 3D, dus het formaat van het responsobject en de lijst van output-URL's komen exact overeen. Raadpleeg Het Vinyl 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 precies éé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/vinyl-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 vinyl figuur bouwtaak. Poll de Haal een Taak op endpoint of abonneer je op de stream totdat de taak SUCCEEDED bereikt, en download vervolgens 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 gerefereerde prototype taak heeft nog niet SUCCEEDED 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 gerefereerde prototype taak bestaat niet, behoort tot een andere gebruiker, of is aangemaakt via de webapp (alleen API-mode prototype taken worden doorgegeven aan bouw).
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden.
Request
POST
/openapi/creative-lab/vinyl-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de" }'
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 geeft 404, en vice versa.
Annuleer een vinyl figuur taak. Als de taak nog PENDING is, worden de credits
die bij het aanmaken zijn verbruikt, teruggestort. Taken die al
IN_PROGRESS zijn, worden geannuleerd zonder terugbetaling (de werknemer kan al
bronnen aan het verbranden 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 retourneert 404.
Padparameters
Name
id
Type
path
Description
Unieke identificatie voor de vinyl figuur taak die geannuleerd moet worden.
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 vinyl 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 vinyl figuur taak om te streamen.
Retourneert
Retourneert een stream van Vinyl Figuur Prototype
of Vinyl 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 vinyl 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. Maximaal toegestaan is 50 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 Vinyl Figuur Prototype Taakobject is een werkunit die Meshy bijhoudt
om een vinyl-figuur-stijl conceptafbeelding te genereren vanuit 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-vinyl-figure-prototype.
Name
name
Type
string
Description
De taaknaam die werd opgegeven toen de taak werd aangemaakt. Lege string als er geen naam werd 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 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 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 0 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 0 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 tonen zonder een brekende wijziging.
Het Vinyl Figuur Bouw Taak object is een werkunit die Meshy bijhoudt om een getextureerd 3D vinyl figuur te genereren vanuit een geslaagde prototype taak. Het gebruikt dezelfde afbeelding-naar-3D pijplijn als Afbeelding naar 3D, dus de uitvoervelden spiegelen dat endpoint's taak 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-vinyl-figure-build.
Name
name
Type
string
Description
De taaknaam die werd 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 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 mislukking).
Name
prompt
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor cross-endpoint compatibiliteit met de gedeelde V2ImageTo3DTaskResponse vorm gebruikt door Afbeelding naar 3D.
Name
negative_prompt
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor cross-endpoint compatibiliteit.
Name
texture_prompt
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor cross-endpoint compatibiliteit.
Name
texture_image_url
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor cross-endpoint compatibiliteit.
Name
model_urls
Type
object
Description
Downloadbare URL's voor het gegenereerde 3D model. De vinyl figuur bouw 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 formaat toevoegingen zonder brekende verandering kunnen worden ingevoegd.
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 basiskleur kaart.
Name
base_color
Type
string
Description
Downloadbare URL naar de basiskleur kaart afbeelding.