Creative Lab — Keycap API

Zdrojová fotografie, kterou Meshy převede na obrázky designu klávesy. Aktuálně podporujeme formáty .jpg, .jpeg, .png a .webp.

Formát je rozpoznán dekódováním obrazových dat, nikoli podle přípony souboru v URL — URL bez přípony nebo taková, která přesměrovává, funguje, pokud se bajty dekódují do podporovaného formátu. HTTP přesměrování jsou následována. Orientace EXIF je normalizována, takže otočená fotografie z telefonu je použita tak, jak vypadá.

Limity: alespoň 32 pixelů na každé straně, nejvýše 178 956 970 pixelů celkem a nejvýše 20 000 000 bajtů po stažení. U Data URI se limit vztahuje na dekódované bajty, takže samotný zdrojový soubor může mít až tuto velikost — je to base64 text, který je zhruba o třetinu větší, což je relevantní pro tělo vašeho požadavku, nikoli pro tento limit. Data URI musí deklarovat typ obsahu image/* a ;base64.

Obrázek lze poskytnout dvěma způsoby:

• Veřejně přístupná URL: URL, která je přístupná z veřejného internetu.
• Data URI: Obrázek zakódovaný v base64 jako data URI. Příklad data URI: data:image/jpeg;base64,<vaše obrazová data zakódovaná v base64>.

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

Když je nastaveno na true, zobrazovací render vrácený v image_urls je transparentní RGBA PNG s odstraněným pozadím, takže jej můžete umístit na jakékoli pozadí.

Toto platí pouze pro zobrazovací render. Kandidát, který zpracovává koncový bod pro sestavení, není ovlivněn, takže 3D výsledek je v obou případech totožný.

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í v podporovaném formátu (.jpg, .jpeg, .png, .webp).
• Rozměry obrázku mimo povolený rozsah: Obrázek je příliš malý, přesahuje maximální velikost souboru nebo přesahuje maximální počet pixelů.
• Nedostupná URL: image_url se nepodařilo stáhnout (404 nebo timeout).
• Neplatné Data URI: Řetězec base64 je poškozený.
• Obsah označen: Vstupní obrázek byl označen moderací NSFW.

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

Účet má aktivní bezplatný plán (pro vytváření úloh je vyžadován placený plán) nebo nemá dostatek kreditů.

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 byla nedostupná, nepodařilo se připravit vstupní obrázek, nebo úlohu nebylo možné vytvořit. V tomto případě nedojde k vytvoření žádné úlohy, takže je bezpečné požadavek zopakovat.

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

Prototypové úlohy vytvořené přes webovou aplikaci nejsou akceptovány — koncový bod pro sestavení přijímá pouze prototypové úlohy vytvořené pomocí POST /openapi/creative-lab/keycap/v1/prototype a jakýkoli jiný zdroj odmítne s chybou 404.

Kandidát, který se má sestavit, převzatý z pole candidate_ids úspěšné prototypové úlohy. Musí patřit k dané úloze; jakákoli jiná hodnota je odmítnuta s chybou 400.

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

Základna keycapu, na které se má sestavovat. Aktuálně je jedinou dostupnou hodnotou cherry-mx-1x1-r1 — standardní keycap 1u v profilu Cherry MX. Plánováno je 3–5 dalších rozšířených standardních velikostí; vlastní velikosti nejsou podporovány.

Cílová velikost vymodelované hlavy v milimetrech: její nejdelší rozměr je škálován na tuto hodnotu. Rozsah: [10, 40]. Hodnoty nad zhruba 32,9 mohou být sníženy, aby hlava stále odpovídala ochrannému limitu základny; dodaný nejdelší rozměr tak může být menší, než bylo požadováno. Použitá hodnota se dnes v objektu úlohy nepromítá zpět — pokud potřebujete potvrdit skutečně obdrženou velikost, změřte ohraničující kvádr sítě keycap-head ve staženém modelu.

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

Požadavek byl nepřijatelný. Časté příčiny:

• Chybějící parametr: input_task_id a candidate_id jsou povinné.
• Neplatné UUID: input_task_id není platné UUID.
• Nadřazená úloha nedokončena úspěšně: Odkazovaná prototypová úloha ještě nedosáhla stavu SUCCEEDED.
• Žádní kandidáti: Prototypová úloha byla úspěšná, ale neprodukovala žádné kandidáty.
• Neznámý kandidát: candidate_id není mezi kandidáty vstupní úlohy.
• Volby mimo rozsah: Jedno z polí options bylo mimo povolený rozsah nebo množinu povolených hodnot.

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

Účet má bezplatný plán (pro vytváření úloh je vyžadován placený plán) nebo nemá dostatek kreditů.

Odkazovaná prototypová úloha neexistuje, patří jinému uživateli nebo byla vytvořena přes webovou aplikaci (do sestavení lze zřetězit pouze prototypové úlohy vytvořené v API režimu).

Překročili jste limit rychlosti.

Došlo k neočekávané chybě na straně serveru — například byla nedostupná služba moderation obsahu, selhalo vložení vstupního obrázku do fronty nebo se nepodařilo úlohu vytvořit. V tomto případě není vytvořena žádná úloha, takže je bezpečné požadavek opakovat.

Jedinečný identifikátor úlohy keycap, kterou chcete načíst.

Jedinečný identifikátor úlohy keycap, kterou chcete zrušit.

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

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

Během rušení došlo k neočekávané chybě na straně serveru. Úloha mohla, ale nemusela být zrušena — před dalším pokusem si ji znovu načtěte pro ověření.

Jedinečný identifikátor úlohy keycap, kterou chcete streamovat.

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

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

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

Pole, podle kterého se řadí. Dostupné hodnoty:

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

Unikátní identifikátor úlohy. Ačkoli jako implementační detail používáme pro id úloh k-sortovatelné UUID, neměli byste dělat žádné předpoklady o formátu id.

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

Název úlohy zadaný při jejím vytvoření. Prázdný řetězec, pokud nebyl název zadán.

Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Progress úlohy. Pokud úloha ještě nezačala, bude tato vlastnost 0. Jakmile úloha uspěje, hodnota se změní na 100.

Časové razítko okamžiku vytvoření úlohy, v milisekundách.

Časové razítko okamžiku zahájení úlohy, v milisekundách. Pokud úloha ještě nezačala, bude tato vlastnost 0.

Časové razítko okamžiku dokončení úlohy, v milisekundách. Pokud úloha ještě není dokončena, bude tato vlastnost 0.

Časové razítko okamžiku, kdy vyprší platnost výsledku úlohy, v milisekundách.

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

Podrobnosti o chybě u neúspěšných úloh. Úplný popis objektu task_error naleznete v části Chyby.

Počet kreditů spotřebovaných touto úlohou. Úloze, která dosáhne stavu SUCCEEDED, je účtována plná částka za danou fázi. Úloha, která nikdy nebyla vytvořena (chyba 4xx v okamžiku požadavku, včetně zamítnutí při moderation), se neúčtuje vůbec. Úloha, která dosáhne stavu FAILED, vrací 0 — poplatek je vrácen, včetně případu asynchronního zablokování při moderation. Zrušení pomocí DELETE vrátí poplatek pouze tehdy, pokud je úloha stále ve stavu PENDING; úloha, která je již IN_PROGRESS, zůstává zpoplatněna, protože práce již byla vynaložena.

Stažitelná URL adresa vykresleného designu hotového keycapu — jak bude kandidát vypadat jako hotový keycap. Obsahuje jednu položku; image_urls[i] odpovídá candidate_ids[i]. Prázdné, dokud úloha nedosáhne stavu SUCCEEDED. URL adresa slouží pouze k zobrazení; koncový bod pro sestavení používá candidate_ids, nikoli tyto URL adresy. Stejný životní cyklus URL jako u model_urls: podepsané, bez hlavičky Authorization, platné do expires_at a stabilní při opětovném načtení úlohy.

Neprůhledné identifikátory kandidátů, paralelní k image_urls. Předejte položku odpovídající vámi zvolenému designu jako candidate_id v požadavku na sestavení. Nedělejte žádné předpoklady o formátu těchto id.

Jedinečný identifikátor úlohy.

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

Název úlohy zadaný při jejím vytvoření. Prázdný řetězec, pokud nebyl název zadán.

Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Postup úlohy (progress). Pokud úloha ještě nebyla zahájena, bude tato hodnota 0. Jakmile úloha úspěšně skončí, hodnota bude 100.

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

Časové razítko zahájení úlohy, v milisekundách.

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

Časové razítko vypršení platnosti výsledku úlohy, v milisekundách.

Počet předcházejících úloh. Má význam pouze tehdy, když je stav PENDING.

Podrobnosti o chybě u neúspěšných úloh. Úplný referenční popis objektu task_error naleznete v části Chyby.

Počet kreditů spotřebovaných touto úlohou. Úloha, která dosáhne stavu SUCCEEDED, je zpoplatněna plnou částkou za danou fázi. Úloha, která nikdy nebyla vytvořena (chyba 4xx v okamžiku požadavku, včetně zamítnutí moderací), není zpoplatněna vůbec. Úloha, která skončí ve stavu FAILED, vrací 0 — poplatek je vrácen, včetně případu asynchronního zablokování moderací. Zrušení pomocí DELETE vrací poplatek pouze tehdy, když je úloha stále ve stavu PENDING; úloha, která je již IN_PROGRESS, zůstává zpoplatněna, protože práce již byla vynaložena.

Stažitelné URL adresy pro vygenerované soubory modelu. Jak balíček GLB, tak balíček OBJ jsou exportovány v reálném měřítku v milimetrech, s orientací Y nahoru a přední stranou klávesy směřující ve směru +Z. Sítě (mesh) se jmenují keycap-head a keycap-base; pokud se základna vrátí k výplňovému vzoru, je přítomna i třetí síť keycap-base-interior pro dutinu pro stem. Nepředpokládejte, že jsou vždy přesně dvě sítě.

Jedná se o podepsané URL adresy: načítejte je bez hlavičky Authorization. Zůstávají platné až do expires_at, tedy 3 dny po finished_at, a opětovné načtení úlohy v tomto časovém okně vrací identickou URL adresu, nikoli nově podepsanou. Soubory si stáhněte a uložte sami před tímto termínem — vypršenou platnost odkazu nelze žádným způsobem obnovit.

Stažitelné URL adresy pro mezistupňové obrázky procesu, klíčované podle druhu. Stejný životní cyklus URL adres jako u model_urls: podepsané, bez hlavičky Authorization, platné až do expires_at a stabilní při opětovném načtení úlohy. Aktuálně generované druhy:

• head_design — obrázek návrhu zvoleného kandidáta, který sestavení použilo (vždy přítomen).
• composite — vykreslený finální náhled hotové klávesy zvoleného kandidáta (přítomen, pokud je k dispozici).
• base_canvas — vymalované plátno základny klávesy (přítomno, pokud je k dispozici).

Považujte množinu klíčů za otevřenou; nové druhy mohou být přidány bez zpětně nekompatibilní změny.