Creative Lab — Keycap API

Källfoto som Meshy ska omvandla till keycap-designbilder. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.

Formatet identifieras genom att avkoda bilddatan, inte utifrån URL:ens filändelse — en URL utan filändelse, eller en som omdirigerar, fungerar så länge byte-datan går att avkoda till ett format som stöds. HTTP-omdirigeringar följs. EXIF-orientering normaliseras, så ett roterat mobilfoto används på det sätt det ser ut.

Begränsningar: minst 32 pixlar på varje sida, högst 178 956 970 pixlar totalt, och högst 20 000 000 byte efter nedladdning. För en Data URI gäller gränsen de avkodade byten, så själva källfilen kan vara upp till den storleken — det är base64-texten som är cirka en tredjedel större, vilket har betydelse för din request-body, inte för denna gräns. En Data URI måste ange en image/*-innehållstyp och ;base64.

Det finns två sätt att ange bilden på:

• Publikt tillgänglig URL: En URL som är tillgänglig från det publika internet.
• Data URI: En base64-kodad data-URI för bilden. Exempel på en Data URI: data:image/jpeg;base64,<din base64-kodade bilddata>.

Valfritt uppgiftsnamn för visningsändamål. Maximalt 100 tecken.

När detta sätts till true är den visade renderingen som returneras i image_urls en transparent RGBA PNG med bakgrunden borttagen, så att du kan sätta ihop den med valfri bakgrund.

Detta gäller endast den visade renderingen. Kandidaten som build-endpointen använder påverkas inte, så 3D-resultatet blir identiskt oavsett.

Begäran kunde inte accepteras. Vanliga orsaker:

• Saknad parameter: image_url krävs.
• Ogiltigt bildformat: Den angivna image_url har inte ett format som stöds (.jpg, .jpeg, .png, .webp).
• Bilddimensioner utanför tillåtet intervall: Bilden är för liten, överskrider den maximala filstorleken, eller överskrider det maximala antalet pixlar.
• Onåbar URL: image_url kunde inte hämtas (404 eller timeout).
• Ogiltig Data URI: Base64-strängen är felaktigt formaterad.
• Innehåll flaggat: Den angivna bilden flaggades av NSFW-moderation.

Autentiseringen misslyckades. Kontrollera din API-nyckel.

Kontot använder den kostnadsfria planen (en betald plan krävs för att skapa uppgifter) eller har otillräckligt med credits.

Den angivna bilden flaggades av moderation för immateriella rättigheter.

Du har överskridit din hastighetsgräns.

Ett oväntat serverfel inträffade — till exempel att innehållsmodereringstjänsten var otillgänglig, att förberedelsen (staging) av den angivna bilden misslyckades, eller att uppgiften inte kunde skapas. I detta fall skapas ingen uppgift, så det är säkert att försöka igen.

Uppgifts-ID för en prototyp-uppgift som skapats via samma OpenAPI-endpoint. Prototypen måste ha skapats av samma Meshy-konto, måste ha nått SUCCEEDED och måste ha genererat minst en kandidat.

Prototyp-uppgifter skapade via webbappen accepteras inte — build-endpointen accepterar endast prototyp-uppgifter som skapats via POST /openapi/creative-lab/keycap/v1/prototype och avvisar alla andra källor med 404.

Kandidaten som ska byggas, hämtad från candidate_ids-arrayen i den lyckade prototyp-uppgiften. Måste tillhöra den uppgiften; alla andra värden avvisas med 400.

Valfritt uppgiftsnamn för visningsändamål. Maximalt 100 tecken.

Keycap-basen att bygga på. För närvarande är det enda tillgängliga värdet cherry-mx-1x1-r1 — en standard Cherry MX-profil 1u keycap. 3–5 ytterligare vanliga standardstorlekar är planerade; anpassade storlekar stöds inte.

Målstorlek för det skulpterade huvudet, i millimeter: dess längsta dimension skalas till detta värde. Intervall: [10, 40]. Värden över ungefär 32.9 kan reduceras så att huvudet fortfarande får plats inom basens skyddande fotavtrycksgräns, så den levererade längsta dimensionen kan bli mindre än begärt. Det tillämpade värdet återges inte i uppgiftsobjektet idag — om du behöver bekräfta storleken du faktiskt fick, mät begränsningsrutan för keycap-head-nätet i den nedladdade modellen.

Vertikal förskjutning som appliceras på huvudet innan det placeras på basen, i millimeter. Intervall: [-5, 5].

Förfrågan var oacceptabel. Vanliga orsaker:

• Saknad parameter: input_task_id och candidate_id krävs.
• Ogiltig UUID: input_task_id är inte en giltig UUID.
• Överordnad ej lyckad: Den refererade prototyp-uppgiften har ännu inte nått SUCCEEDED.
• Inga kandidater: Prototyp-uppgiften lyckades men genererade inga kandidater.
• Okänd kandidat: candidate_id är inte en av inmatningsuppgiftens kandidater.
• Alternativ utanför intervall: Ett av fälten i options låg utanför sitt tillåtna intervall eller enum-uppsättning.

Autentiseringen misslyckades. Kontrollera din API-nyckel.

Kontot har den kostnadsfria planen (en betald plan krävs för att skapa uppgifter) eller har otillräckliga credits.

Den refererade prototyp-uppgiften finns inte, tillhör en annan användare, eller skapades via webbappen (endast prototyp-uppgifter i API-mode kan kedjas till build).

Du har överskridit din hastighetsgräns.

Ett oväntat serverfel inträffade — till exempel var innehållsmoderationstjänsten otillgänglig, det gick inte att förbereda indatabilden, eller uppgiften kunde inte skapas. Ingen uppgift skapas i detta fall, så det är säkert att försöka igen.

Unik identifierare för keycap-uppgiften som ska hämtas.

Unik identifierare för keycap-uppgiften som ska avbrytas.

Uppgiften är redan i ett slutgiltigt tillstånd och kan inte avbrytas.

Uppgiften finns inte, tillhör en annan användare, eller dess steg matchar inte URL-sökvägen.

Ett oväntat serverfel uppstod vid avbrytning. Uppgiften kan eller kan inte ha blivit avbruten — läs den igen för att bekräfta innan du försöker igen.

Unik identifierare för den keycap-uppgift som ska strömmas.

Antingen prototype eller build. Samlingen returnerar endast uppgifter vars steg matchar URL:en — att hämta /prototype returnerar aldrig byggnadsuppgifter och vice versa.

Sidnummer för paginering.

Gräns för sidstorlek. Maximalt tillåtet är 100 objekt.

Fält att sortera efter. Tillgängliga värden:

• +created_at: Sortera efter skapandetid i stigande ordning.
• -created_at: Sortera efter skapandetid i fallande ordning.

Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgiftsid:n som implementationsdetalj, bör du inte göra några antaganden om formatet på id:t.

Uppgiftens typ. Värdet är creative-lab-keycap-prototype.

Uppgiftens namn som angavs när uppgiften skapades. Tom sträng om inget namn angavs.

Uppgiftens status. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Uppgiftens progress. Om uppgiften ännu inte har startat är denna egenskap 0. När uppgiften har lyckats blir den 100.

Tidsstämpel för när uppgiften skapades, i millisekunder.

Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften ännu inte har startat är denna egenskap 0.

Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften ännu inte är avslutad är denna egenskap 0.

Tidsstämpel för när uppgiftens resultat upphör att gälla, i millisekunder.

Antalet föregående uppgifter.

Felinformation för misslyckade uppgifter. Se Fel för den fullständiga referensen för objektet task_error.

Antalet credits som förbrukats av denna uppgift. En uppgift som når SUCCEEDED debiteras hela beloppet för sitt steg. En uppgift som aldrig skapas (ett 4xx-fel vid förfrågningstillfället, inklusive ett moderation-avslag) debiteras inte alls. En uppgift som når FAILED returnerar 0 — avgiften återbetalas, inklusive en asynkron moderation-blockering. Att avbryta via DELETE återbetalar endast medan uppgiften fortfarande är PENDING; en uppgift som redan är IN_PROGRESS förblir debiterad, eftersom arbetet redan har utförts.

Nedladdningsbar URL för renderingen av den färdiga keycap-designen — hur kandidaten ser ut som färdig keycap. Innehåller en enda post; image_urls[i] motsvarar candidate_ids[i]. Tom tills uppgiften når SUCCEEDED. URL:en är endast för visning; build-endpointen använder candidate_ids, inte dessa URL:er. Samma URL-livscykel som model_urls: signerad, ingen Authorization-header, giltig till expires_at, och stabil när uppgiften läses om.

Opaka kandidatidentifierare, parallella med image_urls. Skicka posten som motsvarar din valda design som candidate_id i build-förfrågan. Gör inte några antaganden om formatet på dessa id:n.

Unik identifierare för tasken.

Taskens typ. Värdet är creative-lab-keycap-build.

Tasknamnet som angavs när tasken skapades. Tom sträng om inget namn angavs.

Taskens status. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Taskens progress. Om tasken ännu inte har startats är denna egenskap 0. När tasken har lyckats blir den 100.

Tidsstämpel för när tasken skapades, i millisekunder.

Tidsstämpel för när tasken startades, i millisekunder.

Tidsstämpel för när tasken avslutades, i millisekunder.

Tidsstämpel för när taskens resultat upphör att gälla, i millisekunder.

Antalet föregående tasks. Är endast meningsfullt när status är PENDING.

Felinformation för misslyckade tasks. Se Fel för den fullständiga referensen för task_error-objektet.

Antalet credits som förbrukats av denna task. En task som når SUCCEEDED debiteras hela beloppet för sitt steg. En task som aldrig skapas (ett 4xx-fel vid begäranstillfället, inklusive en moderation-avvisning) debiteras inte alls. En task som når FAILED returnerar 0 — avgiften återbetalas, inklusive vid en asynkron moderation-blockering. Att avbryta via DELETE återbetalar endast medan tasken fortfarande är PENDING; en task som redan är IN_PROGRESS förblir debiterad, eftersom arbetet redan har utförts.

Nedladdningsbara URL:er för de genererade modellfilerna. Både GLB- och OBJ-paketet exporteras i verklig skala i millimeter, Y-upp, med framsidan av keycappen riktad mot +Z. Näten heter keycap-head och keycap-base; när basen faller tillbaka på en mönsterfyllning finns även ett tredje nät, keycap-base-interior, för stamhålan. Utgå inte från att det alltid finns exakt två nät.

Dessa är signerade URL:er: hämta dem utan en Authorization-header. De förblir giltiga tills expires_at, som är 3 dagar efter finished_at, och om tasken läses igen inom det fönstret returneras samma URL istället för en nysignerad. Ladda ner och spara filerna själv innan det inträffar — det finns inget sätt att uppdatera en utgången länk.

Nedladdningsbara URL:er för mellanliggande processbilder, nyckelbaserade efter typ. Samma URL-livscykel som model_urls: signerad, ingen Authorization-header, giltig tills expires_at, och stabil när tasken läses igen. Typer som för närvarande genereras:

• head_design — designbilden för den valda kandidaten som build-processen använde (finns alltid).
• composite — den färdiga keycap-visningsrendreringen av den valda kandidaten (finns när tillgänglig).
• base_canvas — den målade keycap-bas-canvasen (finns när tillgänglig).

Betrakta nyckelsetet som öppet för utökning; nya typer kan läggas till utan att det innebär en brytande ändring.