Creative Lab — Keycap API

Zdrojová fotografie pro Meshy k přeměně na obrázky designu klávesy. V současné době podporujeme formáty .jpg, .jpeg, .png a .webp.

Formát je detekován dekódováním dat obrázku, ne z přípony souboru URL — URL bez přípony nebo taková, která přesměrovává, funguje, pokud bajty dekódují na podporovaný formát. HTTP přesměrování jsou sledována. EXIF orientace je normalizována, takže otočená fotografie z telefonu je použita tak, jak vypadá.

Limity: alespoň 32 pixelů na každé straně, maximálně 178,956,970 pixelů celkem a maximálně 20,000,000 bajtů po stažení. Pro data URI se limit vztahuje na dekódované bajty, takže samotný zdrojový soubor může být až do této velikosti — je to base64 text, který je asi o třetinu větší, což je důležité pro vaše tělo požadavku, ne pro tento limit. Data URI musí deklarovat obsahový typ image/* a ;base64.

Existují dva způsoby, jak poskytnout obrázek:

• Veřejně přístupná URL: URL, která je přístupná z veřejného internetu.
• Data URI: Base64-kódovaná data URI obrázku. Příklad data URI: data:image/jpeg;base64,<vaše base64-kódovaná data obrázku>.

Volitelný název úkolu pro účely zobrazení. Maximálně 100 znaků.

Pokud je nastaveno na true, zobrazený render vrácený v image_urls je průhledný RGBA PNG s odstraněným pozadím, takže jej můžete složit na jakékoli pozadí.

To platí pouze pro zobrazený render. Kandidát, který koncový bod sestavení spotřebovává, není ovlivněn, takže 3D výsledek je stejný v obou případech.

Požadavek byl nepřijatelný. Běžné příčiny:

• Chybějící parametr: image_url je povinný.
• Neplatný formát obrázku: Poskytnutý image_url není podporovaný formát (.jpg, .jpeg, .png, .webp).
• Rozměry obrázku mimo rozsah: Obrázek je příliš malý, překračuje maximální velikost souboru nebo překračuje maximální počet pixelů.
• Nedostupná URL: image_url nemohla být stažena (404 nebo timeout).
• Neplatná Data URI: Base64 řetězec je poškozený.
• Obsah označen: Vstupní obrázek byl označen NSFW moderací.

Autentizace selhala. Zkontrolujte prosím svůj API klíč.

Účet je na bezplatném plánu (pro vytvoření úkolů je vyžadován placený plán) nebo nemá dostatečné kredity.

Vstupní obrázek byl označen moderací duševního vlastnictví.

Překročili jste svůj limit rychlosti.

Došlo k neočekávané chybě na straně serveru — například služba moderace obsahu nebyla dostupná, staging vstupního obrázku selhal nebo úkol nemohl být vytvořen. V tomto případě není vytvořen žádný úkol, takže opakování je bezpečné.

ID úkolu prototypu vytvořeného prostřednictvím tohoto stejného OpenAPI koncového bodu. Prototyp musí být vytvořen stejným účtem Meshy, musí dosáhnout SUCCEEDED a musí produkovat alespoň jednoho kandidáta.

Prototypové úkoly vytvořené prostřednictvím webové aplikace nejsou přijímány — koncový bod pro sestavení přijímá pouze prototypové úkoly produkované POST /openapi/creative-lab/keycap/v1/prototype a odmítá jakýkoli jiný zdroj s 404.

Kandidát k sestavení, vybraný z pole candidate_ids úspěšného prototypového úkolu. Musí patřit k tomuto úkolu; jakákoli jiná hodnota je odmítnuta s 400.

Volitelný název úkolu pro zobrazení. Maximálně 100 znaků.

Základna klávesy, na které se bude stavět. Aktuálně je jedinou dostupnou hodnotou cherry-mx-1x1-r1 — standardní klávesa Cherry MX profilu 1u. Plánuje se 3–5 dalších hlavních standardních velikostí; vlastní velikosti nejsou podporovány.

Cílová velikost sochařské hlavy v milimetrech: její nejdelší rozměr je škálován na tuto hodnotu. Rozsah: [10, 40]. Hodnoty nad přibližně 32.9 mohou být zmenšeny, aby hlava stále zapadala do ochranného limitu základny, takže dodaný nejdelší rozměr může být menší než požadovaný. Aplikovaná hodnota dnes není zpětně odražena v objektu úkolu — pokud potřebujete potvrdit velikost, kterou jste skutečně obdrželi, změřte ohraničující kvádr sítě keycap-head ve staženém modelu.

Vertikální posun aplikovaný na hlavu před jejím usazením na základnu, v milimetrech. Rozsah: [-5, 5].

Požadavek byl nepřijatelný. Běžné příčiny:

• Chybějící parametr: input_task_id a candidate_id jsou povinné.
• Neplatný UUID: input_task_id není platný UUID.
• Rodič nedosáhl úspěchu: Odkazovaný prototypový úkol ještě nedosáhl SUCCEEDED.
• Žádní kandidáti: Prototypový úkol uspěl, ale neprodukoval žádné kandidáty.
• Neznámý kandidát: candidate_id není jedním z kandidátů vstupního úkolu.
• Možnosti mimo rozsah: Jedno z polí options spadlo mimo povolený rozsah nebo množinu hodnot.

Autentizace selhala. Zkontrolujte prosím svůj API klíč.

Účet je na bezplatném plánu (pro vytvoření úkolů je vyžadován placený plán) nebo má nedostatečné kredity.

Odkazovaný prototypový úkol neexistuje, patří jinému uživateli nebo byl vytvořen prostřednictvím webové aplikace (pouze prototypové úkoly v režimu API se řetězí do sestavení).

Překročili jste svůj limit rychlosti.

Došlo k neočekávané chybě na straně serveru — například služba pro moderování obsahu nebyla dostupná, staging vstupního obrázku selhal nebo úkol nemohl být vytvořen. V tomto případě není vytvořen žádný úkol, takže opakování je bezpečné.

Unikátní identifikátor pro úkol keycap, který chcete načíst.

Unikátní identifikátor pro úkol keycap, který má být zrušen.

Úkol je již v konečném stavu a nelze jej zrušit.

Úkol neexistuje, patří jinému uživateli nebo jeho fáze neodpovídá cestě URL.

Došlo k neočekávané chybě na straně serveru při rušení. Úkol mohl, ale nemusel být zrušen — před opakováním jej znovu přečtěte pro potvrzení.

Unikátní identifikátor pro úkol keycap ke streamování.

Buď prototype nebo build. Kolekce vrací pouze úkoly, jejichž fáze odpovídá URL — načítání /prototype nikdy nevrací úkoly sestavení a naopak.

Číslo stránky pro stránkování.

Limit velikosti stránky. Maximální povolené je 100 položek.

Pole pro třídění. Dostupné hodnoty:

• +created_at: Třídit podle času vytvoření vzestupně.
• -created_at: Třídit podle času vytvoření sestupně.

Unikátní identifikátor pro úkol. I když používáme k-tříděné UUID pro id úkolů jako implementační detail, neměli byste dělat žádné předpoklady o formátu id.

Typ úkolu. Hodnota je creative-lab-keycap-prototype.

Název úkolu zadaný při vytvoření úkolu. Prázdný řetězec, pokud nebyl poskytnut žádný název.

Stav úkolu. Možné hodnoty jsou PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Pokrok úkolu. Pokud úkol ještě nezačal, tato vlastnost bude 0. Jakmile úkol uspěje, stane se 100.

Časové razítko, kdy byl úkol vytvořen, v milisekundách.

Časové razítko, kdy byl úkol zahájen, v milisekundách. Pokud úkol ještě nezačal, tato vlastnost bude 0.

Časové razítko, kdy byl úkol dokončen, v milisekundách. Pokud úkol ještě není dokončen, tato vlastnost bude 0.

Časové razítko, kdy výsledek úkolu vyprší, v milisekundách.

Počet předcházejících úkolů.

Podrobnosti o chybě pro neúspěšné úkoly. Viz Chyby pro úplnou referenci objektu task_error.

Počet kreditů spotřebovaných tímto úkolem. Úkol, který dosáhne SUCCEEDED, je účtován plnou částkou za svou fázi. Úkol, který nikdy není vytvořen (chyba 4xx v době žádosti, včetně odmítnutí moderace) není účtován vůbec. Úkol, který dosáhne FAILED, vrací 0 — poplatek je vrácen, včetně asynchronního blokování moderace. Zrušení prostřednictvím DELETE vrací peníze pouze pokud je úkol stále PENDING; úkol, který je již IN_PROGRESS, zůstává účtován, protože práce byla vynaložena.

Stahovatelná URL vykreslení dokončeného návrhu klávesy — jak kandidát vypadá jako dokončená klávesa. Obsahuje jeden záznam; image_urls[i] odpovídá candidate_ids[i]. Prázdné, dokud úkol nedosáhne SUCCEEDED. URL je pouze pro zobrazení; koncový bod sestavení spotřebovává candidate_ids, ne tyto URL. Stejný životní cyklus URL jako model_urls: podepsané, bez hlavičky Authorization, platné do expires_at a stabilní, když je úkol znovu přečten.

Neprůhledné identifikátory kandidátů, paralelní k image_urls. Předávejte záznam odpovídající vašemu vybranému návrhu jako candidate_id v žádosti o sestavení. Nedělejte žádné předpoklady o formátu těchto id.

Unikátní identifikátor pro úkol.

Typ úkolu. Hodnota je creative-lab-keycap-build.

Název úkolu zadaný při vytvoření úkolu. Prázdný řetězec, pokud nebyl zadán žádný název.

Stav úkolu. Možné hodnoty jsou PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Postup úkolu. Pokud úkol ještě nezačal, tato vlastnost bude 0. Jakmile úkol uspěje, stane se 100.

Časové razítko, kdy byl úkol vytvořen, v milisekundách.

Časové razítko, kdy byl úkol zahájen, v milisekundách.

Časové razítko, kdy byl úkol dokončen, v milisekundách.

Časové razítko, kdy výsledek úkolu vyprší, v milisekundách.

Počet předcházejících úkolů. Má smysl pouze, když je stav PENDING.

Podrobnosti o chybách pro neúspěšné úkoly. Viz Chyby pro úplný odkaz na objekt task_error.

Počet kreditů spotřebovaných tímto úkolem. Úkol, který dosáhne SUCCEEDED, je účtován plnou částkou za svou fázi. Úkol, který nikdy nevznikne (chyba 4xx v době požadavku, včetně odmítnutí moderace), není účtován vůbec. Úkol, který dosáhne FAILED, vrátí 0 — poplatek je vrácen, včetně asynchronního bloku moderace. Zrušení pomocí DELETE vrací peníze pouze tehdy, když je úkol stále PENDING; úkol, který je již IN_PROGRESS, zůstává účtován, protože práce byla vynaložena.

Stahovatelné URL pro generované modelové artefakty. Oba balíčky GLB a OBJ jsou exportovány v reálném měřítku v milimetrech, Y-up, s přední stranou klávesy směřující +Z. Sítě jsou pojmenovány keycap-head a keycap-base; když základna přejde na vzorovou výplň, je také přítomna třetí síť keycap-base-interior pro dutinu stonku. Nepředpokládejte přesně dvě sítě.

Jedná se o podepsané URL: stáhněte je bez hlavičky Authorization. Zůstávají platné do expires_at, což je 3 dny po finished_at, a opětovné čtení úkolu v tomto okně vrátí identické URL místo nově podepsaného. Stáhněte a uložte soubory sami předtím — není možné obnovit vypršený odkaz.

Stahovatelné URL pro mezilehlé procesní obrázky, klíčované podle druhu. Stejný životní cyklus URL jako model_urls: podepsané, bez hlavičky Authorization, platné do expires_at, a stabilní při opětovném čtení úkolu. Aktuálně emitované druhy:

• head_design — designový obrázek vybraného kandidáta, který build spotřeboval (vždy přítomen).
• composite — render zobrazení dokončené klávesy vybraného kandidáta (přítomen, když je k dispozici).
• base_canvas — malované plátno základny klávesy (přítomen, když je k dispozici).

Považujte klíčovou sadu za otevřenou; nové druhy mohou být přidány bez přerušení změny.