Creative Lab Keycap API

De foto die moet worden omgezet in een keycap-ontwerp, als een openbare URL of een data-URI (data:image/jpeg;base64,<your base64-encoded image data>).

De afbeelding moet een JPG-, JPEG-, PNG- of WebP-bestand zijn van maximaal 20 MB (20.000.000 bytes). Elke zijde moet minstens 32 pixels zijn, en de afbeelding mag in totaal maximaal 178.956.970 pixels bevatten. Een afbeelding buiten deze limieten geeft 400 terug.

Meshy detecteert het formaat op basis van de afbeeldingsgegevens, niet op basis van de bestandsextensie in de URL. Een URL zonder extensie werkt, en Meshy volgt HTTP-omleidingen. Meshy past de EXIF-oriëntatie toe, zodat een gedraaide telefoonfoto er uitziet zoals bedoeld.

Een data-URI moet base64-gecodeerd zijn met een afbeeldingstype, zoals data:image/png;base64,..., en de gedecodeerde afbeelding moet JPEG, PNG of WebP zijn. De limiet van 20 MB geldt voor de gedecodeerde afbeelding, dus de base64-tekst kan ongeveer een derde groter zijn.

Een naam voor de taak, tot 100 tekens. Deze komt terug in het veld name van de taak. Een langere naam geeft 400 terug.

Of de achtergrond uit de prototypeafbeelding moet worden verwijderd. true geeft een transparante RGBA-PNG terug, zodat je de keycap op elke achtergrond kunt plaatsen. Als Meshy de achtergrond niet kan verwijderen, geeft het de afbeelding mét achtergrond terug, en de taak slaagt alsnog.

Het kopontwerp dat de build omzet naar 3D, behoudt in beide gevallen zijn achtergrond. De build schildert de keycap-basis op basis van de afbeelding in image_urls, zonder achtergrond als je true hebt meegegeven. De build geeft die afbeelding terug als process_image_urls.composite.

Het verzoek kan niet worden uitgevoerd. Bijvoorbeeld:

• image_url ontbreekt.
• De afbeelding is geen JPG-, JPEG-, PNG- of WebP-bestand.
• De afbeelding is te klein, groter dan 20 MB, of overschrijdt het maximale aantal pixels.
• Meshy kan de afbeelding niet downloaden, bijvoorbeeld omdat de URL 404 teruggeeft of time-out geeft.
• De data-URI is geen geldige base64.
• De afbeelding is gemarkeerd als NSFW.

Het foutbericht geeft aan welk probleem er is gevonden. Herstel het verzoek en verstuur het opnieuw.

De API-sleutel ontbreekt of is ongeldig. Controleer de Authorization-header.

Een van het volgende is van toepassing:

• Het account heeft onvoldoende credits.
• De API-sleutel, werkruimte of het lid heeft zijn creditlimiet bereikt.
• Het account gebruikt het gratis abonnement.

Controleer je credits en abonnement en probeer het opnieuw.

Je team heeft IP-filtering ingeschakeld, en Meshy heeft de afbeelding gemarkeerd vanwege intellectueel eigendom van derden. Stuur een afbeelding waarvoor je gebruiksrechten hebt.

Een van deze limieten is bereikt:

• Je hebt meer verzoeken verstuurd dan je rate limit toestaat. Wacht een paar seconden en probeer het opnieuw. Zie Rate limits.
• Er staan te veel van je taken in de wachtrij of lopen er te veel. Wacht tot er een paar zijn voltooid en probeer het opnieuw.
• Bij een onbeperkt abonnement zonder resterende credits heb je het aantal taken bereikt dat zonder credits kan worden uitgevoerd. Wacht tot een taak is voltooid, of voeg credits toe.

Meshy heeft een serverfout ondervonden, bijvoorbeeld omdat contentmoderatie of de controle op intellectueel eigendom niet kon worden uitgevoerd, of omdat Meshy de afbeelding niet kon opslaan. Meshy maakt de taak niet aan en vergoedt eventueel in rekening gebrachte credits. Probeer het verzoek opnieuw.

De ID van de prototypetaak die moet worden gebouwd. Dit moet een taak zijn die uw account heeft aangemaakt met POST /openapi/creative-lab/keycap/v1/prototype, met de status SUCCEEDED.

Een ID die niet overeenkomt met een van uw Keycap-prototypetaken uit de API geeft 404 terug, inclusief een prototype dat in de web-app is gemaakt.

De kandidaat die moet worden gebouwd, uit de candidate_ids-array van de prototypetaak. Een waarde die niet in die array voorkomt, geeft 400 terug.

Een naam voor de taak, tot 100 tekens. Deze komt terug in het name-veld van de taak. Een langere naam geeft 400 terug.

De keycapbasis waarop gebouwd wordt. De enige waarde is cherry-mx-1x1-r1, een standaard Cherry MX-profiel 1u keycap. Aangepaste groottes worden niet ondersteund, en elke andere waarde geeft 400 terug.

De grootte van de kop langs de langste afmeting, in millimeters, van 10 tot 40. Meshy schaalt de kop zodat de langste afmeting overeenkomt met deze waarde. Een waarde buiten het bereik geeft 400 terug.

Bij een waarde boven ongeveer 32.9 kan Meshy de grootte verkleinen zodat de kop binnen de beschermende voetafdruklimiet van de basis past. De kop kan dan kleiner uitvallen dan gevraagd. Het taakobject geeft de door Meshy toegepaste grootte niet terug. Om dit te controleren, meet u de bounding box van de keycap-head-mesh in het model.

De verticale verschuiving die op de kop wordt toegepast voordat Meshy deze op de basis plaatst, in millimeters, van -5 tot 5. Een waarde buiten het bereik geeft 400 terug.

Het verzoek kan niet worden uitgevoerd. Bijvoorbeeld:

• input_task_id ontbreekt of is geen geldige taak-ID.
• De status van de prototypetaak is niet SUCCEEDED. Als deze nog wordt uitgevoerd, wacht en probeer het opnieuw. Als deze is mislukt of geannuleerd, maak een nieuwe prototypetaak aan.
• De prototypetaak is geslaagd maar heeft geen kandidaten. Maak een nieuwe prototypetaak aan.
• candidate_id ontbreekt, of staat niet in de candidate_ids van de prototypetaak. Stuur een waarde uit die array.
• Een veld in options valt buiten het bereik, of base_model is geen beschikbare waarde.

Het foutbericht geeft aan welk probleem is gevonden.

De API-sleutel ontbreekt of is ongeldig. Controleer de Authorization-header.

Een van het volgende is van toepassing:

• Het account heeft niet genoeg credits.
• De API-sleutel, werkruimte of lid heeft de creditlimiet bereikt.
• Het account heeft een gratis abonnement.

Controleer uw credits en abonnement, en probeer het opnieuw.

input_task_id komt niet overeen met een Keycap-prototypetaak die uw account met de API heeft aangemaakt. Een prototype dat in de web-app is gemaakt, geeft eveneens 404 terug. Stuur de result-ID uit een antwoord op het aanmaken van een prototype.

Een van deze limieten is bereikt:

• U hebt meer verzoeken verstuurd dan uw rate limit toestaat. Wacht een paar seconden en probeer het opnieuw. Zie Rate limits.
• Er staan te veel van uw taken in de wachtrij of worden uitgevoerd. Wacht tot sommige zijn voltooid en probeer het opnieuw.
• Bij een onbeperkt abonnement zonder resterende credits hebt u het aantal taken bereikt dat zonder credits kan worden uitgevoerd. Wacht tot een taak is voltooid, of voeg credits toe.

Meshy kon de taak niet aanmaken vanwege een serverfout. Meshy vergoedt eventueel in rekening gebrachte credits. Probeer het verzoek opnieuw.

De taak-ID uit de aanmaakrespons.

id is geen geldige taak-ID. Stuur de result-ID uit de aanmaakrespons.

Uw team heeft IP Filtering ingeschakeld, en Meshy heeft de afbeelding van de prototype-taak gemarkeerd wegens intellectueel eigendom van derden. Build-taken en teams in het Enterprise-plan krijgen deze fout niet. Maak een prototype-taak aan met een afbeelding waarvoor u gebruiksrechten heeft.

Er bestaat geen Keycap-taak met deze ID voor uw account, of de fase van de taak komt niet overeen met het pad. Controleer de ID en gebruik /prototype of /build passend bij de taak.

Meshy kon de controle op intellectueel eigendom niet uitvoeren. Probeer het verzoek opnieuw.

Het ID van de te annuleren taak.

Een van het volgende is van toepassing:

• id is geen geldig taak-ID. Stuur het result-ID uit het aanmaakantwoord.
• De taak heeft al een definitieve status (SUCCEEDED, FAILED of CANCELED), dus kan deze niet worden geannuleerd.

Er bestaat geen Keycap-taak met dit ID binnen jouw account, of de fase van de taak komt niet overeen met het pad. Controleer het ID en gebruik /prototype of /build om overeen te komen met de taak.

Meshy liep tegen een serverfout aan tijdens het annuleren van de taak, dus de taak is mogelijk wel of niet geannuleerd. Haal de taak op om de status ervan te controleren voordat je het opnieuw probeert.

De taak-ID uit de aanmaakreactie.

De fase die moet worden weergegeven, prototype of build.

De pagina die moet worden geretourneerd, van 1 tot 255. 0 geeft de eerste pagina terug. Een waarde buiten 0 tot 255 geeft 400 terug.

Aantal taken per pagina, tot 100. Een waarde van 101 tot 255 geeft 100 taken terug, en 0 gebruikt de standaardwaarde. Een waarde buiten 0 tot 255 geeft 400 terug.

De sorteervolgorde.

Beschikbare waarden:

• -created_at: nieuwste eerst
• +created_at: oudste eerst

De taak-ID. Vertrouw niet op het formaat ervan.

Het taaktype, altijd creative-lab-keycap-prototype.

De name die je hebt opgegeven bij het aanmaken van de taak, of "" als je er geen hebt opgegeven.

De status van de taak.

Beschikbare waarden:

• PENDING: wacht in de wachtrij
• IN_PROGRESS: resultaat wordt gegenereerd
• SUCCEEDED: definitief, met resultaat
• FAILED: definitief, met de reden in task_error
• CANCELED: definitief, zonder resultaat

Percentage van het voltooide werk, van 0 tot 100. Dit is 0 totdat de taak start en 100 zodra deze slaagt.

Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.

Tijdstip waarop een worker de taak is gestart, in Unix-milliseconden. null tot dat moment.

Tijdstip waarop de taak een definitieve status heeft bereikt, in Unix-milliseconden. null tot dat moment.

Tijdstip waarop het resultaat van de taak verloopt, in Unix-milliseconden. Dit is 3 dagen na finished_at, of 3 dagen na created_at totdat de taak is voltooid. Voor Enterprise-accounts, die API-resultaten onbeperkt bewaren, is dit ongeveer 100 jaar later. Zie Asset-retentie.

De positie van de taak in de wachtrij terwijl deze PENDING is. 1 betekent dat deze als volgende start. 0 nadat de taak de wachtrij heeft verlaten, en altijd 0 in lijstresultaten.

Waarom de taak is mislukt. null tenzij status gelijk is aan FAILED. Zie Fouten.

Aantal credits dat voor de taak in rekening is gebracht, na eventuele terugbetaling. Voor een aanvraag die een fout retourneert, worden geen kosten in rekening gebracht. Een mislukte taak heeft de waarde 0, omdat Meshy deze terugbetaalt. Annuleren leidt alleen tot terugbetaling van een taak terwijl deze PENDING is. Als Meshy de kosten niet kan uitlezen, laat een get- of streamrespons dit veld weg, en retourneert een lijstaanvraag 500. Probeer het verzoek in dat geval opnieuw.

Downloadlink(en) voor de afbeelding van de voltooide keycap. De array bevat één URL zodra de taak is geslaagd, en is daarvoor leeg. image_urls[i] toont de kandidaat in candidate_ids[i].

Deze URL's zijn bedoeld voor weergave. De build endpoint neemt een item uit candidate_ids, geen URL. Het zijn ondertekende URL's, dus haal ze op zonder Authorization-header. Ze blijven geldig tot expires_at, en het opnieuw ophalen van de taak levert dezelfde URL's op.

ID's van de kandidaten, in dezelfde volgorde als image_urls. Om een kandidaat te bouwen, stuur je de bijbehorende ID als candidate_id mee in het build-verzoek. Vertrouw niet op het formaat van deze ID's.

De task-ID. Ga niet uit van een bepaalde opmaak.

Het task-type, altijd creative-lab-keycap-build.

De name die je hebt meegestuurd bij het aanmaken van de taak, of "" als je er geen hebt meegestuurd.

De status van de taak.

Beschikbare waarden:

• PENDING: wacht in de wachtrij
• IN_PROGRESS: genereert het resultaat
• SUCCEEDED: definitief, met het resultaat
• FAILED: definitief, met de reden in task_error
• CANCELED: definitief, zonder resultaat

Percentage van het voltooide werk, van 0 tot 100. Dit is 0 totdat de taak start en 100 wanneer deze slaagt.

Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.

Tijdstip waarop een worker de taak heeft gestart, in Unix-milliseconden. null tot die tijd.

Tijdstip waarop de taak een definitieve status heeft bereikt, in Unix-milliseconden. null tot die tijd.

Tijdstip waarop het resultaat van de taak verloopt, in Unix-milliseconden. Dit is 3 dagen na finished_at, of 3 dagen na created_at totdat de taak voltooid is. Voor Enterprise-accounts, die API-resultaten onbeperkt bewaren, is dit ongeveer 100 jaar later. Zie Asset-retentie.

De positie van de taak in de wachtrij terwijl deze PENDING is. 1 betekent dat deze als volgende start. 0 nadat de taak de wachtrij heeft verlaten, en altijd 0 in lijstresultaten.

Waarom de taak is mislukt. null tenzij status gelijk is aan FAILED. Zie Fouten.

Aantal credits dat voor de taak in rekening is gebracht, na eventuele terugbetaling. Voor een verzoek dat een fout retourneert, worden geen kosten in rekening gebracht. Een mislukte taak heeft de waarde 0, omdat Meshy deze terugbetaalt. Annuleren betaalt een taak alleen terug zolang deze PENDING is. Als Meshy de kosten niet kan uitlezen, laat een get- of stream-respons dit veld weg, en retourneert een lijstverzoek 500. Probeer het verzoek in dat geval opnieuw.

Downloadlinks voor het 3D-model. Meshy exporteert het GLB-bestand en de OBJ-bundel op werkelijke schaal in millimeters, Y-up, met de voorkant van de keycap gericht naar +Z.

Het model heeft meshes genaamd keycap-head en keycap-base. Wanneer Meshy terugvalt op een patroonvulling voor de basis, heeft het model ook een keycap-base-interior-mesh voor de stamholte. Ga er niet van uit dat het model precies twee meshes heeft.

Dit zijn ondertekende URL's, dus haal ze op zonder een Authorization-header. Ze blijven geldig tot expires_at, en het opnieuw ophalen van de taak vóór die tijd levert dezelfde URL's op. Een verlopen URL kan niet worden vernieuwd, dus download en bewaar de bestanden voor die tijd.

Downloadlinks voor afbeeldingen van de stappen van de build, gesleuteld op type. Net als model_urls zijn dit ondertekende URL's, dus haal ze op zonder een Authorization-header. Ze blijven geldig tot expires_at, en het opnieuw ophalen van de taak levert dezelfde URL's op.

Dit kan de volgende sleutels bevatten:

• head_design: de ontwerpafbeelding van de gekozen kandidaat, die de build heeft omgezet naar 3D. Altijd aanwezig.
• composite: de afbeelding van de voltooide keycap voor de gekozen kandidaat, waarvan de build de basis heeft geschilderd. Kan ontbreken.
• base_canvas: de geschilderde keycap-basis. Kan ontbreken.

Meshy kan sleutels toevoegen, dus negeer een sleutel die je niet herkent.