Creative Lab — Keycap API

Bronfoto die Meshy omzet in keycap-ontwerpafbeeldingen. We ondersteunen momenteel de indelingen .jpg, .jpeg, .png en .webp.

De indeling wordt gedetecteerd door de afbeeldingsgegevens te decoderen, niet aan de hand van de bestandsextensie van de URL — een URL zonder extensie, of een die doorverwijst, werkt zolang de bytes decoderen naar een ondersteunde indeling. HTTP-redirects worden gevolgd. EXIF-oriëntatie wordt genormaliseerd, zodat een gedraaide telefoonfoto wordt gebruikt zoals hij eruitziet.

Beperkingen: minstens 32 pixels aan elke zijde, hoogstens 178.956.970 pixels in totaal, en hoogstens 20.000.000 bytes na download. 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 relevant is voor uw requestbody, niet voor deze limiet. Een data-URI moet een image/*-content-type en ;base64 bevatten.

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,<uw 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 waarvan de achtergrond is verwijderd, zodat u deze op elke achtergrond kunt samenvoegen.

Dit geldt alleen voor de weergaverender. De kandidaat die de build-endpoint gebruikt, wordt hierdoor niet beïnvloed, dus het 3D-resultaat is in beide gevallen identiek.

Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:

• Ontbrekende parameter: image_url is verplicht.
• Ongeldige afbeeldingsindeling: de opgegeven image_url heeft geen ondersteunde indeling (.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-tekenreeks is onjuist opgemaakt.
• Content gemarkeerd: de invoerafbeelding is gemarkeerd door NSFW-moderation.

Authenticatie is mislukt. Controleer uw API-sleutel.

Het account heeft een gratis abonnement (een betaald abonnement is vereist om taken aan te maken) of heeft onvoldoende credits.

De invoerafbeelding is gemarkeerd door moderation voor intellectueel eigendom.

U heeft uw rate limit overschreden.

Er is een onverwachte serverfout opgetreden — bijvoorbeeld doordat de content-moderationservice niet beschikbaar was, het klaarzetten van de invoerafbeelding mislukte, of de taak niet kon worden aangemaakt. In dit geval wordt er geen taak aangemaakt, dus opnieuw proberen is veilig.

De task-ID van een prototypetaak die via dezelfde OpenAPI-endpoint is aangemaakt. Het prototype moet zijn aangemaakt door hetzelfde Meshy-account, moet SUCCEEDED hebben bereikt, en moet minstens één kandidaat hebben opgeleverd.

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

De kandidaat om te bouwen, afkomstig uit de candidate_ids-array van de geslaagde prototypetaak. Moet bij die taak horen; elke andere waarde wordt afgewezen met 400.

Optionele taaknaam voor weergavedoeleinden. Maximaal 100 tekens.

De keycap-basis waarop wordt gebouwd. Momenteel is de enige beschikbare waarde cherry-mx-1x1-r1 — een standaard Cherry MX-profiel 1u keycap. 3–5 extra mainstream standaardformaten staan gepland; aangepaste formaten worden niet ondersteund.

Doelgrootte van de gesculptureerde kop, in millimeters: de langste afmeting ervan wordt geschaald naar deze waarde. Bereik: [10, 40]. Waarden boven ongeveer 32.9 kunnen worden verlaagd 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 momenteel niet teruggegeven op het task-object — als u de daadwerkelijk ontvangen grootte wilt bevestigen, 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 onaanvaardbaar. Veelvoorkomende oorzaken:

• Ontbrekende parameter: input_task_id en candidate_id zijn verplicht.
• Ongeldige UUID: De input_task_id is geen geldige UUID.
• Ouder niet geslaagd: De verwezen prototypetaak heeft SUCCEEDED nog niet bereikt.
• Geen kandidaten: De prototypetaak is geslaagd maar heeft geen kandidaten opgeleverd.
• Onbekende kandidaat: candidate_id behoort niet tot de kandidaten van de invoertaak.
• Opties buiten bereik: Een van de options-velden viel buiten het toegestane bereik of de toegestane enum-set.

Authenticatie mislukt. Controleer uw API-sleutel.

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

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

U heeft uw rate limit overschreden.

Er is een onverwachte serverzijdige fout opgetreden — bijvoorbeeld de content-moderationservice was niet beschikbaar, het klaarzetten van de invoerafbeelding mislukte, of de taak kon niet worden aangemaakt. In dit geval wordt er geen taak aangemaakt, dus het is veilig om het opnieuw te proberen.

Unieke identificatie van de op te halen keycap-taak.

Unieke identifier voor de te annuleren keycap-taak.

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

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

Er is een onverwachte serverfout opgetreden tijdens het annuleren. De taak is mogelijk wel of niet geannuleerd — lees deze opnieuw om dit te bevestigen voordat u het opnieuw probeert.

Unieke identificatie voor de keycap-taak die gestreamd moet worden.

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

Paginanummer voor paginering.

Paginagrootte-limiet. Maximaal toegestaan 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-keycap-prototype.

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

Status van de taak. Mogelijke waarden zijn een van 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 afgerond, in milliseconden. Als de taak nog niet is afgerond, 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. Een taak die SUCCEEDED bereikt, wordt het volledige bedrag voor die fase in rekening gebracht. Een taak die nooit wordt aangemaakt (een 4xx op het moment van het verzoek, inclusief een afwijzing door moderation) wordt helemaal niet in rekening gebracht. Een taak die FAILED bereikt, geeft 0 terug — het bedrag wordt terugbetaald, ook bij een asynchrone blokkade door moderation. Annuleren via DELETE betaalt alleen terug 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 van de render van het uiteindelijke keycap-ontwerp — hoe de kandidaat eruitziet als 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 build-endpoint gebruikt candidate_ids, niet deze URL's. Dezelfde URL-levenscyclus als model_urls: ondertekend, geen Authorization-header, geldig tot expires_at, en stabiel wanneer de taak opnieuw wordt uitgelezen.

Ondoorzichtige kandidaat-identifiers, parallel aan image_urls. Geef het item dat overeenkomt met je gekozen ontwerp door als candidate_id van het buildverzoek. Doe geen aannames over het formaat van deze id's.

Unieke identifier voor de task.

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

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

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

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

Tijdstempel van het moment waarop de task is aangemaakt, in milliseconden.

Tijdstempel van het moment waarop de task is gestart, in milliseconden.

Tijdstempel van het moment waarop de task is voltooid, in milliseconden.

Tijdstempel van het moment waarop het taakresultaat verloopt, in milliseconden.

Het aantal voorgaande tasks. Alleen relevant wanneer status PENDING is.

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

Het aantal credits dat door deze task is verbruikt. Een task die SUCCEEDED bereikt, wordt volledig in rekening gebracht voor de betreffende fase. Een task die nooit wordt aangemaakt (een 4xx op het moment van de aanvraag, inclusief een afwijzing door moderation) wordt helemaal niet in rekening gebracht. Een task die FAILED bereikt, geeft 0 terug — de kosten worden terugbetaald, ook bij een asynchrone blokkering door moderation. Annuleren via DELETE betaalt de kosten alleen terug zolang de task nog PENDING is; een task die al IN_PROGRESS is, blijft in rekening gebracht, omdat het werk al is uitgevoerd.

Downloadbare URL's voor de gegenereerde modelbestanden. Zowel de GLB- als de OBJ-bundel worden geëxporteerd op schaal van echte millimeters, Y-omhoog, met de voorkant van de keycap gericht op +Z. Meshes hebben de namen 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 er niet van uit dat er precies twee meshes zijn.

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 uitlezen van de task binnen dat venster levert dezelfde URL op in plaats van een nieuw ondertekende. Download en bewaar de bestanden zelf vóór die tijd — er is geen manier om een verlopen link te vernieuwen.

Downloadbare URL's voor tussentijdse procesafbeeldingen, gesleuteld op type. Dezelfde URL-levenscyclus als model_urls: ondertekend, geen Authorization-header, geldig tot expires_at, en stabiel wanneer de task opnieuw wordt uitgelezen. Momenteel geleverde typen:

• head_design — de door de build gebruikte ontwerpafbeelding van de gekozen kandidaat (altijd aanwezig).
• composite — de render van de afgewerkte keycap van de gekozen kandidaat (aanwezig indien beschikbaar).
• base_canvas — het beschilderde canvas van de keycap-basis (aanwezig indien beschikbaar).

Beschouw de set sleutels als open voor uitbreiding; er kunnen nieuwe typen worden toegevoegd zonder een breaking change.