Creative Lab — Keycap API

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

Formatet detekteras genom att avkoda bilddata, inte från URL:ens filändelse — en URL utan ändelse, eller en som omdirigerar, fungerar så länge bytena avkodas till ett stödt format. HTTP-omdirigeringar följs. EXIF-orientering normaliseras, så ett roterat telefonfoto används som 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 när det har laddats ner. För en data URI gäller gränsen för de avkodade bytena, så källfilen själv kan vara upp till den storleken — det är base64-texten som är ungefär en tredjedel större, vilket är viktigt för din begäran, inte för denna gräns. En data URI måste deklarera en image/* innehållstyp och ;base64.

Det finns två sätt att tillhandahålla bilden:

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

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

När den är inställd på true, är visningsrenderingen som returneras i image_urls en transparent RGBA PNG med bakgrunden borttagen, så att du kan komponera den på vilken bakgrund som helst.

Detta gäller endast visningsrenderingen. Kandidaten som bygg-endpointen använder påverkas inte, så 3D-resultatet är identiskt oavsett.

Begäran var oacceptabel. Vanliga orsaker:

• Saknad parameter: image_url krävs.
• Ogiltigt bildformat: Den angivna image_url är inte ett stödt format (.jpg, .jpeg, .png, .webp).
• Bilddimensioner utanför räckvidd: Bilden är för liten, överskrider max filstorlek eller överskrider max antal pixlar.
• Oåtkomlig URL: image_url kunde inte laddas ner (404 eller timeout).
• Ogiltig Data URI: Base64-strängen är felaktig.
• Innehåll flaggat: Ingångsbilden flaggades av NSFW-moderation.

Autentisering misslyckades. Kontrollera din API-nyckel.

Kontot är på gratisplanen (en betald plan krävs för att skapa uppgifter) eller har otillräckliga credits.

Ingångsbilden flaggades av immaterialrättslig moderation.

Du har överskridit din hastighetsgräns.

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

Task-ID för en prototyptask skapad via denna samma OpenAPI endpoint. Prototypen måste ha skapats av samma Meshy-konto, måste ha nått SUCCEEDED och måste ha producerat minst en kandidat.

Prototyptasks skapade genom webappen accepteras inte — bygg-endpointen accepterar endast prototyptasks producerade av POST /openapi/creative-lab/keycap/v1/prototype och avvisar alla andra källor med 404.

Kandidaten att bygga, tagen från candidate_ids-arrayen av den lyckade prototyptasken. Måste tillhöra den tasken; alla andra värden avvisas med 400.

Valfritt tasknamn för visningsändamål. Max 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 planeras; anpassade storlekar stöds inte.

Målstorlek för det skulpterade huvudet, i millimeter: dess längsta dimension skalas till detta värde. Område: [10, 40]. Värden över ungefär 32.9 kan reduceras så att huvudet fortfarande passar basens skyddande fotavtrycksgräns, så den levererade längsta dimensionen kan vara mindre än begärd. Det tillämpade värdet återges inte i task-objektet 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 applicerad på huvudet innan det placeras på basen, i millimeter. Område: [-5, 5].

Begäran var oacceptabel. Vanliga orsaker:

• Saknad parameter: input_task_id och candidate_id är obligatoriska.
• Ogiltig UUID: input_task_id är inte en giltig UUID.
• Förälder inte lyckad: Den refererade prototyptasken har inte nått SUCCEEDED än.
• Inga kandidater: Prototyptasken lyckades men producerade inga kandidater.
• Okänd kandidat: candidate_id är inte en av input taskens kandidater.
• Alternativ utanför räckvidd: Ett av options-fälten föll utanför dess tillåtna räckvidd eller enum-set.

Autentisering misslyckades. Kontrollera din API-nyckel.

Kontot är på gratisplanen (en betald plan krävs för att skapa tasks) eller har otillräckliga credits.

Den refererade prototyptasken existerar inte, tillhör en annan användare eller skapades genom webappen (endast API-mode prototyptasks kedjas till bygg).

Du har överskridit din hastighetsgräns.

Ett oväntat serverfel inträffade — till exempel var innehållsmodereringstjänsten otillgänglig, staging av inmatningsbilden misslyckades, eller tasken kunde inte skapas. Ingen task 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 slutligt tillstånd och kan inte avbrytas.

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

Ett oväntat serverfel inträffade vid avbrytandet. Uppgiften kan ha avbrutits eller inte — läs om den för att bekräfta innan du försöker igen.

Unik identifierare för keycap-uppgiften att strömma.

Antingen prototype eller build. Samlingen returnerar endast uppgifter vars stadium matchar URL:en — hämtning av /prototype returnerar aldrig bygguppgifter och vice versa.

Sidnummer för paginering.

Sidstorleksgräns. Max 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 uppgifts-id som implementeringsdetalj, bör du inte göra några antaganden om formatet på id.

Typ av uppgift. Värdet är creative-lab-keycap-prototype.

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

Status för uppgiften. Möjliga värden är en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Framsteg för uppgiften. Om uppgiften inte har startat än, kommer denna egenskap att vara 0. När uppgiften har lyckats, kommer detta att bli 100.

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

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

Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften inte har avslutats än, kommer denna egenskap att vara 0.

Tidsstämpel för när uppgiftsresultatet går ut, i millisekunder.

Antalet föregående uppgifter.

Felformationer för misslyckade uppgifter. Se Fel för fullständig referens av task_error-objektet.

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 (en 4xx vid begäran, inklusive en moderation avslag) debiteras inte alls. En uppgift som når FAILED returnerar 0 — avgiften återbetalas, inklusive en asynkron moderation block. Avbokning via DELETE återbetalar endast medan uppgiften fortfarande är PENDING; en uppgift som redan är IN_PROGRESS förblir debiterad, eftersom arbetet har utförts.

Nedladdningsbar URL för den färdiga nyckelkapseldesignens rendering — hur kandidaten ser ut som en färdig nyckelkapsel. 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; bygg-endpointen förbrukar candidate_ids, inte dessa URL:er. Samma URL-livscykel som model_urls: signerad, ingen Authorization-header, giltig tills expires_at, och stabil när uppgiften läses om.

Ogenomskinliga kandidatidentifierare, parallella med image_urls. Skicka posten som matchar din valda design som byggbegärans candidate_id. Gör inga antaganden om formatet på dessa id.

Unik identifierare för uppgiften.

Typ av uppgift. Värdet är creative-lab-keycap-build.

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

Status för uppgiften. Möjliga värden är en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Framsteg för uppgiften. Om uppgiften inte har startat ännu kommer denna egenskap att vara 0. När uppgiften har lyckats kommer detta att bli 100.

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

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

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

Tidsstämpel för när uppgiftsresultatet går ut, i millisekunder.

Antalet föregående uppgifter. Meningsfullt endast när status är PENDING.

Felformationer för misslyckade uppgifter. Se Fel för fullständig referens av task_error-objektet.

Antalet credits som förbrukats av denna uppgift. En uppgift som når SUCCEEDED debiteras fullt belopp för sin fas. En uppgift som aldrig skapas (en 4xx vid begäran, inklusive en moderation avslag) debiteras inte alls. En uppgift som når FAILED returnerar 0 — avgiften återbetalas, inklusive en asynkron moderation blockering. Avbrytande via DELETE återbetalar endast medan uppgiften fortfarande är PENDING; en uppgift som redan är IN_PROGRESS förblir debiterad, eftersom arbetet har utförts.

Nedladdningsbara URL:er för de genererade modellartefakterna. Både GLB och OBJ-paketet exporteras i verklig värld millimeterskala, Y-up, med framsidan av tangentkappen vänd mot +Z. Nät är namngivna keycap-head och keycap-base; när basen faller tillbaka till ett mönsterfyllning finns också ett tredje nät keycap-base-interior för stamkaviteten. Förutsätt inte exakt två nät.

Dessa är signerade URL:er: hämta dem utan en Authorization-header. De förblir giltiga till expires_at, vilket är 3 dagar efter finished_at, och att läsa om uppgiften inom det fönstret returnerar samma URL istället för en ny signerad. Ladda ner och lagra filerna själv innan dess — det finns inget sätt att förnya en utgången länk.

Nedladdningsbara URL:er för mellanliggande processbilder, nycklade efter typ. Samma URL-livscykel som model_urls: signerade, ingen Authorization-header, giltiga till expires_at, och stabila när uppgiften läses om. För närvarande emitterade typer:

• head_design — den valda kandidatens designbild som byggprocessen förbrukade (alltid närvarande).
• composite — den färdiga tangentkappens visningsrendering av den valda kandidaten (närvarande när tillgänglig).
• base_canvas — den målade tangentkappens basduk (närvarande när tillgänglig).

Behandla nyckeluppsättningen som öppen; nya typer kan läggas till utan en brytande förändring.