Creative Lab — sleutelhanger API

Bronfoto die Meshy inkleurt tot een sleutelhanger-klare conceptafbeelding. 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 publieke 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>.

Optionele tasknaam voor weergavedoeleinden. Maximaal 100 tekens.

Dit labelt de taak in je dashboard en tasklijsten. Het wordt niet gegraveerd op de sleutelhanger — gebruik daarvoor name_text.

Tekst om op de sleutelhanger te graveren, zoals de naam van een huisdier of persoon. Maximaal 10 tekens, geteld als Unicode-tekens in plaats van bytes, zodat een 10 tekens lange Chinese, Japanse of Koreaanse naam wordt geaccepteerd. Laat dit veld leeg om een sleutelhanger zonder gravure te produceren.

Omringende witruimte wordt verwijderd en onzichtbare opmaaktekens worden verwijderd voordat de tekst wordt gebruikt. De resulterende waarde wordt geretourneerd als name_text op het prototype task object, zodat je precies kunt bevestigen wat er gegraveerd zal worden voordat je betaalt voor de buildfase.

De gravure wordt hier toegepast, in de prototypefase. De buildfase erft deze automatisch en accepteert geen eigen name_text.

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 composeren.

Dit heeft alleen invloed op de afbeelding die deze endpoint retourneert. Het staat los van de gelijknamige buildoptie (standaard true), die achtergrondverwijdering vóór het reliëfproces regelt.

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 misvormd.
• Gravure te lang: name_text is langer dan 10 tekens. Het verzoek wordt geweigerd in plaats van afgekapt, zodat je nooit wordt gefactureerd voor een sleutelhanger met een verkorte naam.
• Content gemarkeerd: de invoerafbeelding werd gemarkeerd door NSFW- of intellectuele-eigendom-moderation, of de name_text-gravure werd gemarkeerd door NSFW-moderation. De gravure wordt alleen gescreend op NSFW-content — screening op intellectuele eigendom is alleen van toepassing op de afbeelding.

Authenticatie is mislukt. Controleer je API-sleutel.

Onvoldoende credits om deze taak uit te voeren.

Je hebt je rate limit overschreden.

De task ID van een prototypetaak die is aangemaakt via dezelfde OpenAPI-endpoint. Het prototype moet zijn aangemaakt met dezelfde API-sleutel, moet SUCCEEDED hebben bereikt en moet exact één kandidaatafbeelding hebben opgeleverd.

Prototypetaken die via de webapp zijn aangemaakt worden niet geaccepteerd — de build-endpoint accepteert uitsluitend prototypetaken die zijn geproduceerd door POST /openapi/creative-lab/keychain/v1/prototype en wijst elke andere herkomst af met 404.

Optionele taaknaam voor weergavedoeleinden. Maximaal 100 tekens.

Omtreksilhouet van de sleutelhangermedaille. Beschikbare waarden:

• circle (standaard)
• rounded-rect
• hexagon
• shield
• star

Zijlengte van het begrenzende vierkant van de sleutelhanger, in millimeter. Bereik: (0, 400].

Maximale reliëfhoogte boven de basis, in millimeter. Bereik: [0, 20].

Verticale verschuiving die vóór de extrusie op het reliëf wordt toegepast, in millimeter. Bereik: [0, 20].

Dikte van de vlakke basisplaat achter het reliëf, in millimeter. Bereik: [0, 20].

Of de achterkant van de medaille wordt afgesloten als een gesloten oppervlak. Zet op false voor een open schaal.

Overdrachtscurve die depth-map-waarden naar reliëfhoogte omzet. Beschikbare waarden:

• linear (standaard)
• gamma
• s-curve

Vormparameter voor de overdrachtscurve (alleen relevant wanneer relief_curve gelijk is aan gamma). Bereik: (0, 10].

Keer de interpretatie van de depth map om, zodat donkerdere gebieden een hoger reliëf krijgen.

Sterkte van de gladstrijking die op de depth map wordt toegepast voordat het reliëf wordt geëxtraheerd. Bereik: [0, 10].

Verticale schaalvermenigvuldiger die boven op relief_height_mm wordt toegepast. Bereik: (0, 10].

Low-pass-drempel voor depth-map-waarden; alles daaronder wordt afgekapt naar nul. Bereik: [0, 1].

Verwijder automatisch de achtergrond van de conceptafbeelding van het prototype vóór het reliëferen.

Dit staat los van de gelijknamige prototypeparameter (standaard false), die bepaalt of de prototypeafbeelding zelf met transparantie wordt geretourneerd.

Meshresolutie die voor de export wordt gebruikt. Bereik: [64, 2048].

Artefactbundel die door de build wordt geretourneerd. Beschikbare waarden:

• glb (standaard) — retourneert één model.glb onder model_urls.glb.
• obj — zipt model.obj + model.mtl + texture.png en retourneert de bundel onder model_urls.obj.
• zip — zipt elk artefact dat de generator produceert en retourneert de bundel onder model_urls.bundle_zip.

Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:

• Ontbrekende parameter: input_task_id is vereist.
• Ongeldige UUID: De input_task_id is geen geldige UUID.
• Bovenliggende taak niet geslaagd: De verwezen prototypetaak heeft SUCCEEDED nog niet bereikt.
• Geen kandidaat: De prototypetaak is geslaagd, maar heeft geen kandidaatafbeelding opgeleverd.
• Options buiten bereik: Een van de options-velden viel buiten het toegestane bereik of de toegestane enum-set.

Authenticatie mislukt. Controleer uw API-sleutel.

Onvoldoende credits om deze taak uit te voeren.

De verwezen prototypetaak bestaat niet, behoort tot een andere gebruiker, of is aangemaakt via de webapp (alleen prototypetaken in API-mode kunnen worden doorgeschakeld naar een build).

U heeft uw rate limit overschreden.

Unieke identifier voor de sleutelhanger-taak die moet worden opgehaald.

Unieke identificatie voor de te annuleren sleutelhangertaak.

De taak heeft al een eindstatus bereikt en kan niet worden geannuleerd.

De taak bestaat niet, behoort tot een andere gebruiker, of de fase komt niet overeen met het URL-pad.

Unieke identifier voor de sleutelhanger-taak die gestreamd moet worden.

Ofwel prototype of build. De collectie retourneert alleen taken waarvan de stage overeenkomt met de URL — het ophalen van /prototype retourneert nooit build-taken en omgekeerd.

Paginanummer voor paginering.

Paginagroottelimiet. Het maximaal toegestane aantal is 100 items.

Veld om op te sorteren. Beschikbare waarden:

• +created_at: Sorteer op aanmaaktijd in oplopende volgorde.
• -created_at: Sorteer op aanmaaktijd in aflopende volgorde.

Unieke identifier voor de taak. Hoewel we als implementatiedetail een k-sorteerbare UUID gebruiken voor taak-id's, mag je geen aannames doen over het formaat van de id.

Type van de taak. De waarde is creative-lab-keychain-prototype.

De taaknaam die is opgegeven bij het aanmaken van de taak. Lege string als er geen naam is opgegeven.

De gravure die op deze sleutelhanger is toegepast, na het bijsnijden en verwijderen van onzichtbare opmaaktekens. Afwezig wanneer de taak is aangemaakt zonder name_text. Vergelijk dit met wat je hebt verzonden om te bevestigen dat de tekst de codering van je HTTP-client heeft overleefd.

Status van de taak. Mogelijke waarden zijn PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress van de taak. Als de taak nog niet is gestart, is deze eigenschap 0. Zodra de taak is geslaagd, wordt dit 100.

Tijdstempel van wanneer de taak is aangemaakt, in milliseconden.

Tijdstempel van wanneer de taak is gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap 0.

Tijdstempel van wanneer de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap 0.

Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.

Het aantal voorafgaande taken.

Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.

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 een mislukking).

Downloadbare URL's voor de conceptafbeeldingskandidaten die door deze prototypetaak 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.

Unieke identificatie voor de taak.

Type van de taak. De waarde is creative-lab-keychain-build.

De taaknaam die is opgegeven bij het aanmaken van de taak. Lege tekenreeks als er geen naam is opgegeven.

Status van de taak. Mogelijke waarden zijn PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Voortgang van de taak. Als de taak nog niet is gestart, is deze eigenschap 0. Zodra de taak is geslaagd, wordt dit 100.

Tijdstempel van wanneer de taak is aangemaakt, in milliseconden.

Tijdstempel van wanneer de taak is gestart, in milliseconden.

Tijdstempel van wanneer de taak is voltooid, in milliseconden.

Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.

Het aantal voorafgaande taken. Alleen relevant wanneer de status PENDING is.

Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.

Het aantal credits dat door deze taak is verbruikt. Geeft 0 terug voor FAILED-taken (credits worden bij mislukking terugbetaald).

Downloadbare URL's voor het gegenereerde artefact, gesleuteld op artefactnaam. Bevat altijd precies één item — het formaat dat is aangevraagd via output.format in het buildverzoek. De sleutel komt overeen met het aangevraagde formaat: