Creative Lab — Keycap API

Bronfoto voor Meshy om om te zetten in keycap-ontwerpafbeeldingen. We ondersteunen momenteel de formaten .jpg, .jpeg, .png en .webp.

Het formaat wordt gedetecteerd door het decoderen van de afbeeldingsgegevens, niet van de bestandsextensie van de URL — een URL zonder extensie, of een die omleidt, werkt zolang de bytes decoderen naar een ondersteund formaat. HTTP-omleidingen worden gevolgd. EXIF-oriëntatie wordt genormaliseerd, dus een gedraaide telefoonfoto wordt gebruikt zoals deze eruitziet.

Limieten: minimaal 32 pixels aan elke zijde, maximaal 178,956,970 pixels in totaal, en maximaal 20,000,000 bytes eenmaal gedownload. Voor een data URI geldt de limiet voor de gedecodeerde bytes, dus het bronbestand zelf mag tot die grootte zijn — het is de base64-tekst die ongeveer een derde groter is, wat van belang is voor je request body, niet voor deze limiet. Een data URI moet een image/* contenttype en ;base64 declareren.

Er zijn twee manieren om de afbeelding te verstrekken:

• 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,<je base64-gecodeerde afbeeldingsgegevens>.

Optionele taaknaam voor weergavedoeleinden. Maximaal 100 tekens.

Wanneer ingesteld op true, is de weergaverender die wordt geretourneerd in image_urls een transparante RGBA PNG met de achtergrond verwijderd, zodat je deze op elke achtergrond kunt samenstellen.

Dit geldt alleen voor de weergaverender. De kandidaat die de build endpoint verbruikt, blijft onaangetast, dus het 3D-resultaat is in beide gevallen identiek.

Het verzoek was onacceptabel. Veelvoorkomende oorzaken:

• Ontbrekende parameter: image_url is vereist.
• Ongeldig afbeeldingsformaat: De verstrekte image_url is 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 ongeldig.
• Inhoud gemarkeerd: De invoerafbeelding is gemarkeerd door NSFW moderation.

Authenticatie mislukt. Controleer je API-sleutel.

Het account bevindt zich op het gratis plan (een betaald plan is vereist om taken te maken) of heeft onvoldoende credits.

De invoerafbeelding is gemarkeerd door intellectuele eigendom moderation.

Je hebt je rate limit overschreden.

Er is een onverwachte server-side fout opgetreden — bijvoorbeeld de content-moderation service was niet beschikbaar, het voorbereiden van de invoerafbeelding is mislukt, of de taak kon niet worden aangemaakt. Er wordt in dit geval geen taak aangemaakt, dus opnieuw proberen is veilig.

De taak-ID van een prototype taak die via dezezelfde OpenAPI endpoint is aangemaakt. Het prototype moet zijn aangemaakt door hetzelfde Meshy-account, moet SUCCEEDED hebben bereikt, en moet ten minste één kandidaat hebben geproduceerd.

Prototype taken die via de webapp zijn aangemaakt worden niet geaccepteerd — de build endpoint accepteert alleen prototype taken geproduceerd door POST /openapi/creative-lab/keycap/v1/prototype en weigert elke andere bron met 404.

De kandidaat om te bouwen, genomen uit de candidate_ids array van de geslaagde prototype taak. Moet tot die taak behoren; elke andere waarde wordt afgewezen met 400.

Optionele taaknaam voor weergavedoeleinden. Maximum 100 tekens.

De keycap basis om op te bouwen. Momenteel is de enige beschikbare waarde cherry-mx-1x1-r1 — een standaard Cherry MX profiel 1u keycap. 3–5 extra gangbare standaardmaten zijn gepland; aangepaste maten worden niet ondersteund.

Doelgrootte van de gebeeldhouwde kop, in millimeters: de langste afmeting wordt geschaald naar deze waarde. Bereik: [10, 40]. Waarden boven ongeveer 32.9 kunnen worden verkleind zodat de kop nog steeds binnen de beschermende voetafdruklimiet van de basis past, waardoor de geleverde langste afmeting kleiner kan zijn dan gevraagd. De toegepaste waarde wordt vandaag niet teruggegeven op het taakobject — als je de grootte wilt bevestigen die je daadwerkelijk hebt ontvangen, meet dan de bounding box van de keycap-head mesh in het gedownloade model.

Verticale offset toegepast op de kop voordat deze op de basis wordt geplaatst, in millimeters. Bereik: [-5, 5].

Het verzoek was onacceptabel. Veelvoorkomende oorzaken:

• Ontbrekende parameter: input_task_id en candidate_id zijn vereist.
• Ongeldige UUID: De input_task_id is geen geldige UUID.
• Ouder niet geslaagd: De genoemde prototype taak heeft SUCCEEDED nog niet bereikt.
• Geen kandidaten: De prototype taak is geslaagd maar heeft geen kandidaten geproduceerd.
• Onbekende kandidaat: candidate_id is niet een van de kandidaten van de input taak.
• Opties buiten bereik: Een van de options velden viel buiten het toegestane bereik of enum set.

Authenticatie mislukt. Controleer je API-sleutel.

Het account is op het gratis plan (een betaald plan is vereist om taken te maken) of heeft onvoldoende credits.

De genoemde prototype taak bestaat niet, behoort tot een andere gebruiker, of is aangemaakt via de webapp (alleen API-modus prototype taken schakelen over naar build).

Je hebt je rate limit overschreden.

Er is een onverwachte server-side fout opgetreden — bijvoorbeeld de content-moderation service was niet beschikbaar, het voorbereiden van de input afbeelding is mislukt, of de taak kon niet worden aangemaakt. Er wordt in dit geval geen taak aangemaakt, dus opnieuw proberen is veilig.

Unieke identificatie voor de keycap-taak om op te halen.

Unieke identificatie voor de keycap taak om te annuleren.

De taak is al in een eindstatus en kan niet worden geannuleerd.

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

Er is een onverwachte serverfout opgetreden tijdens het annuleren. De taak kan al dan niet zijn geannuleerd — lees deze opnieuw om te bevestigen voordat u het opnieuw probeert.

Unieke identificatie voor de keycap taak om te streamen.

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 vice versa.

Paginanummer voor paginering.

Limiet voor paginagrootte. Maximum toegestaan is 100 items.

Veld om op te sorteren. Beschikbare waarden:

• +created_at: Sorteren op creatietijd in oplopende volgorde.
• -created_at: Sorteren op creatietijd in aflopende volgorde.

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

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

De taaknaam die werd opgegeven toen de taak werd aangemaakt. Lege string als er geen naam werd opgegeven.

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

Voortgang van de taak. Als de taak nog niet is gestart, zal deze eigenschap 0 zijn. 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, zal deze eigenschap 0 zijn.

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

Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.

Het aantal voorafgaande taken.

Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.

Het aantal credits dat door deze taak is verbruikt. Een taak die SUCCEEDED bereikt, wordt het volledige bedrag voor zijn fase in rekening gebracht. Een taak die nooit wordt aangemaakt (een 4xx op het moment van de aanvraag, inclusief een moderatieafwijzing) wordt helemaal niet in rekening gebracht. Een taak die FAILED bereikt, retourneert 0 — de kosten worden terugbetaald, inclusief een asynchrone moderatieblokkering. Annuleren via DELETE wordt alleen terugbetaald zolang de taak nog PENDING is; een taak die al IN_PROGRESS is, blijft in rekening gebracht, omdat het werk is besteed.

Downloadbare URL van de afgewerkte keycap-ontwerprender — hoe de kandidaat eruitziet als een afgewerkte keycap. Bevat één item; image_urls[i] komt overeen met candidate_ids[i]. Leeg totdat de taak SUCCEEDED bereikt. De URL is alleen voor weergave; de bouwendpoint verbruikt candidate_ids, niet deze URL's. Zelfde URL-levenscyclus als model_urls: ondertekend, geen Authorization header, geldig tot expires_at, en stabiel wanneer de taak opnieuw wordt gelezen.

Ondoorzichtige kandidaat-identificaties, parallel aan image_urls. Geef de vermelding die overeenkomt met je gekozen ontwerp door als de candidate_id van het bouwverzoek. Maak geen aannames over het formaat van deze id's.

Unieke identificatie voor de taak.

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

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

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

Voortgang van de taak. Als de taak nog niet is gestart, zal deze eigenschap 0 zijn. 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. Betekenisvol alleen wanneer de status PENDING is.

Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.

Het aantal credits dat door deze taak is verbruikt. Een taak die SUCCEEDED bereikt, wordt het volledige bedrag voor zijn fase in rekening gebracht. Een taak die nooit wordt aangemaakt (een 4xx op het moment van aanvraag, inclusief een moderatie-afwijzing) wordt helemaal niet in rekening gebracht. Een taak die FAILED bereikt, retourneert 0 — de kosten worden terugbetaald, inclusief een asynchrone moderatieblokkering. Annuleren via DELETE geeft alleen een terugbetaling zolang de taak nog PENDING is; een taak die al IN_PROGRESS is, blijft in rekening gebracht, omdat het werk al is verricht.

Downloadbare URL's voor de gegenereerde modelartefacten. Zowel de GLB als de OBJ-bundel worden geëxporteerd op echte wereld millimeterschaal, Y-up, met de voorkant van de keycap gericht naar +Z. Meshes worden genoemd keycap-head en keycap-base; wanneer de basis terugvalt op een patroonvulling, is er ook een derde mesh keycap-base-interior aanwezig voor de steelholte. Ga niet uit van precies twee meshes.

Dit zijn ondertekende URL's: haal ze op zonder een Authorization-header. Ze blijven geldig tot expires_at, wat 3 dagen na finished_at is, en het opnieuw lezen van de taak binnen dat venster retourneert dezelfde URL in plaats van een vers ondertekende. Download en sla de bestanden zelf op voor die tijd — er is geen manier om een verlopen link te vernieuwen.

Downloadbare URL's voor tussentijdse procesafbeeldingen, gesorteerd op soort. Zelfde URL-levenscyclus als model_urls: ondertekend, geen Authorization-header, geldig tot expires_at, en stabiel wanneer de taak opnieuw wordt gelezen. Momenteel uitgegeven soorten:

• head_design — het ontwerpbeeld van de gekozen kandidaat dat de build heeft verbruikt (altijd aanwezig).
• composite — de weergave van de afgewerkte keycap van de gekozen kandidaat (aanwezig wanneer beschikbaar).
• base_canvas — het geschilderde keycap-basis canvas (aanwezig wanneer beschikbaar).

Behandel de sleutelset als open-eindig; nieuwe soorten kunnen worden toegevoegd zonder een brekende verandering.