Verander een bronfoto in een vinylfiguur met groot hoofd in twee
stappen: prototype genereert een gestileerde conceptafbeelding van je
inputfoto, vervolgens verandert build dat conceptbeeld in een 3D model
met texture. De twee stappen zijn gekoppeld via input_task_id.
POST /openapi/creative-lab/vinyl-figure/v1/prototype
Genereer een enkel conceptafbeelding in vinylfigurengestijl vanuit de bronfoto. De geretourneerde taak-ID is wat je doorgeeft als input_task_id naar de build endpoint. Raadpleeg Het Vinylfiguur 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 vinylfiguur. We ondersteunen momenteel de formaten .jpg, .jpeg, .png en .webp.
Er zijn twee manieren om de afbeelding aan te leveren:
Openbare 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.
Returnwaarden
De result eigenschap van de reactie bevat de taak id van de nieuw gecreëerde vinylfiguur prototype taak. Raadpleeg de Haalt 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
De aanvraag was niet acceptabel. 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 maximaal aantal pixels.
Onbereikbare URL: De image_url kon niet gedownload worden (404 of timeout).
Ongeldige Data URI: De base64 string is onjuist.
Inhoud gemarkeerd: De invoerafbeelding is gemarkeerd door NSFW of intellectueel 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
# Fase 1: genereer een conceptafbeelding in vinylfigurengestijlcurl https://api.meshy.ai/openapi/creative-lab/vinyl-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":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Genereer het uiteindelijke geavanceerde 3D vinyl figuur van een geslaagde prototype-opdracht. De build voert dezelfde afbeelding-naar-3D pijplijn uit als Afbeelding naar 3D, dus het antwoordobjectformaat en de lijst van uitvoer-URL's komen exact overeen. Raadpleeg Het Vinyl Figuur Opdracht Object voor het antwoordformaat.
Parameters
Name
input_task_id
Type
string
Verplicht
Description
De taak-ID van een prototype-opdracht gemaakt via dezezelfde OpenAPI endpoint. Het prototype moet zijn gemaakt met dezelfde API-sleutel, moet de status SUCCEEDED hebben bereikt en moet precies één kandidaat-afbeelding hebben geproduceerd.
Prototype-opdrachten gemaakt via de webapp worden niet geaccepteerd — de build endpoint accepteert alleen prototype-opdrachten geproduceerd door POST /openapi/creative-lab/vinyl-figure/v1/prototype en weigert elke andere bron met 404.
Name
name
Type
string
Description
Optionele opdrachtnaam voor weergavedoeleinden. Maximaal 100 tekens.
Returns
De result eigenschap van het antwoord bevat de taak id van de nieuw gemaakte vinyl figuur opbouw taak. Vraag de Haal een Taak op endpoint of abonneer je op de stream totdat de taak de status SUCCEEDED bereikt, en download dan de geavanceerde GLB van model_urls.glb (of het OBJ + MTL paar van model_urls.obj en model_urls.mtl als jouw 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-opdracht heeft nog niet de status SUCCEEDED bereikt.
Geen kandidaat: De prototype-opdracht is geslaagd maar heeft geen kandidaat-afbeelding opgeleverd.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
404 - Not Found
Description
De gerefereerde prototype-opdracht bestaat niet, behoort tot een andere gebruiker, of is gemaakt via de webapp (alleen API-mode prototype-opdrachten koppelen aan build).
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden.
Verzoek
POST
/openapi/creative-lab/vinyl-figure/v1/build
# Fase 2: bouw voort op een geslaagde prototype-opdrachtcurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \ -X POST \ -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 geldige 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 vinyl figuur taak. Als de taak nog PENDING is, worden de bij aanmaak verbruikte credits teruggegeven. Taken die al IN_PROGRESS zijn, worden geannuleerd zonder restitutie (de werknemer kan al bronnen aan het verbranden zijn). Taken die al een eindtoestand 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 vinyl 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 eindtoestand 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 realtime-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 op
/prototype/:buildId/stream stuurt een enkel 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 responsstream
alleen de noodzakelijke progress en status velden bevatten.
// Voorbeeld van een error event (verkeerde fase of taak niet gevonden)event: errordata: {"status_code": 404,"message": "Task not found"}// Voorbeelden van berichtsgebeurtenissen illustreren taakvoortgang.// Voor PENDING of IN_PROGRESS taken, zal de responsstream niet alle velden bevatten.event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","type": "creative-lab-vinyl-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1752969700000,"started_at": 1752969710000,"finished_at": 1752969735000,"expires_at": 1753228935000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/texture_0.png?Expires=***" } ]}
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 uit de andere fase zijn niet inbegrepen
in beide reacties.
Pad Parameters
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.
Query Parameters
Name
page_num
Type
integer
standaard 1
Description
Paginanummer voor paginering.
Name
page_size
Type
integer
standaard 10
Description
Paginagrootte limiet. 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 Taak object is een werkeenheid die Meshy bijhoudt
om een vinyl-figuur-stijl conceptafbeelding te genereren van een bronfoto.
De output van deze fase wordt via input_task_id gekoppeld aan
de opbouwfase.
Eigenschappen
Name
id
Type
string
Description
Unieke identificatie voor de taak. Hoewel we een k-sortable UUID gebruiken voor taak ids 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 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
Vooruitgang 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 vertegenwoordigt het aantal milliseconden verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339 standaard. Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 GMT wordt gerepresenteerd 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 0.
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 0.
Name
expires_at
Type
timestamp
Description
Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.
Name
preceding_tasks
Type
integer
Description
Het aantal voorafgaande 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 teruggeboekt bij mislukking).
Name
image_urls
Type
array of strings
Description
Downloadbare URLs voor de conceptbeeld 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 bieden zonder een brekende wijziging.
Het Vinyl Figuur Bouw Taak object is een werk eenheid die Meshy bijhoudt
om een getextureerde 3D vinyl figuur te genereren van een geslaagde prototype taak.
Het gebruikt dezelfde afbeelding-naar-3D pijplijn als Afbeelding naar 3D,
dus de uitvoervelden spiegelen het 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 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, is deze eigenschap 0. Zodra de taak geslaagd is, 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 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 teruggestort bij een mislukking).
Name
prompt
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor compatibiliteit tussen endpoints met de gedeelde V2ImageTo3DTaskResponse vorm gebruikt door Afbeelding naar 3D.
Name
negative_prompt
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor compatibiliteit tussen endpoints.
Name
texture_prompt
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor compatibiliteit tussen endpoints.
Name
texture_image_url
Type
string
Description
Altijd leeg voor vinyl figuur bouw. Aanwezig voor compatibiliteit tussen endpoints.
Name
model_urls
Type
object
Description
Downloadbare URL's voor het gegenereerde 3D-model. De vinyl figuur bouw produceert 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 een breuk verandering 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 OBJ begeleidingsmateriaal MTL bestand. Combineer met obj en de invoer 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 basiskleurenkaart.
Name
base_color
Type
string
Description
Downloadbare URL naar de basiskleurkaart afbeelding.