Webhooky vs. dotazování v Meshy API: Kdy jsou výsledky připraveny

Generační úlohy v Meshy API (Text to 3D, Image to 3D, Rigging a další) běží asynchronně – odešlete úlohu a poté musíte zjistit, kdy je hotová, než si stáhnete výsledek. Tento článek vysvětluje životní cyklus úlohy a dva podporované způsoby, jak zjistit, že je úloha dokončena: dotazování (polling) a webhooky – a také jak se vyhnout nejčastějšímu problému „chyby při načítání modelu“.

Každá generační úloha prochází malou sadou stavů, které jsou vráceny v poli status objektu úlohy:

• PENDING – úloha byla zařazena do fronty, ale zpracování ještě nezačalo.

• IN_PROGRESS – úloha je aktivně zpracovávána. Pole progress (0–100) roste s tím, jak práce postupuje.

• SUCCEEDED – úloha byla úspěšně dokončena a progress je 100. Výsledné URL (soubory modelů, textury, náhledy) jsou nyní k dispozici v odpovědi.

• FAILED – úlohu nebylo možné dokončit. Kredity za neúspěšné úlohy jsou automaticky vráceny.

• CANCELED – úloha byla před dokončením zrušena.

Nejdůležitější pravidlo při integraci s API: nikdy se nepokoušejte načítat ani používat výsledná URL, dokud stav úlohy status není SUCCEEDED. Čtení výsledků, dokud je úloha ve stavu PENDING nebo IN_PROGRESS, je nejčastější příčinou hlášení „chyby při načítání modelu“.

Dotazování znamená opakované volání endpointu „get task“ pro ID vaší úlohy, dokud nedosáhne koncového stavu (SUCCEEDED, FAILED nebo CANCELED). Jednoduchá smyčka dotazování vypadá takto:

• Odešlete požadavek na generování a uložte vrácené id úlohy.

• V pravidelných intervalech (typicky několik sekund) volejte odpovídající endpoint „retrieve task“ (např. endpoint Text to 3D nebo Image to 3D task-by-id).

• V každé odpovědi kontrolujte pole status. Pokračujte v dotazování, dokud je hodnota PENDING nebo IN_PROGRESS.

• Přestaňte dotazovat, jakmile je status ve stavu SUCCEEDED (přečtěte výsledná URL), FAILED nebo CANCELED.

• Přidejte do svého klienta rozumný timeout/omezovač počtu pokusů, aby zaseknutá úloha nezpůsobovala dotazování donekonečna.

Dotazování je jednoduché a dobře funguje pro skripty, dávkové úlohy a integrace s nízkým objemem. U integrací s vysokým objemem nebo nároky na latenci je obvykle lepším řešením webhook.

Místo opakovaného ptání „už je to hotové?“ můžete požádat Meshy, aby upozornilo váš server okamžikem dokončení úlohy. Chcete-li používat webhooky:

• Nakonfigurujte URL webhooku (callback), ke kterému se Meshy může dostat – to se obvykle nastavuje na úrovni nastavení účtu/API nebo předává jako parametr v požadavku na generování, v závislosti na endpointu.

• Ujistěte se, že váš endpoint je veřejně dostupný přes HTTPS a rychle odpovídá (okamžitě vraťte stav 2xx a poté payload zpracujte asynchronně).

• Když úloha dosáhne koncového stavu, Meshy odešle na váš endpoint payload obsahující id úlohy a její konečný status.

• Po přijetí si načtěte kompletní detaily úlohy podle id prostřednictvím API, místo abyste spoléhali pouze na tělo webhooku – tím zajistíte, že máte autoritativní a aktuální výsledek.

Webhooky snižují počet zbytečných volání API a poskytují téměř okamžité upozornění, ale přesto byste si měli ponechat pravidelné dotazování jako zálohu pro případy, kdy doručení webhooku může být zmeškáno nebo zpožděno (např. kvůli přechodné síťové chybě na vaší straně).

Ať už používáte dotazování nebo webhooky, váš kód pro zpracování výsledků by měl být idempotentní – bezpečně spustitelný vícekrát pro stejnou úlohu bez vedlejších efektů. Je to důležité, protože:

• Webhook může být pro stejnou úlohu doručen více než jednou (opakované pokusy na straně odesílatele, duplikace v síti atd.).

• Smyčka dotazování i obsluha webhooku se mohou současně pokoušet zpracovat tutéž dokončenou úlohu, pokud obě běží.

Aby zpracování zůstalo idempotentní, klíčujte svou logiku podle id úlohy – například před opakováním zkontrolujte, zda jste výsledky pro dané id již neuložili/nestáhli, a udělejte z „označit jako zpracované“ jediný atomický krok ve své vlastní databázi.

Odpověď s "status": "SUCCEEDED" a "progress": 100 je jediný signál, který zaručuje, že výsledný payload (URL modelů, textury, miniatury) je kompletní a bezpečně použitelný. Konkrétně ve svém kódu:

• Ověřte status === "SUCCEEDED" před čtením čehokoli z polí result/URL modelu.

• Nespoléhejte samotné na progress – vždy kontrolujte také status, protože progress může krátce ukazovat vysoké hodnoty, než je úloha plně dokončena.

• Výsledné soubory si stáhněte co nejdříve po dosažení SUCCEEDED – vygenerované assety jsou na serverech Meshy uchovávány pouze omezenou dobu, po které již URL nebudou fungovat.

Většina hlášení typu „nemohu načíst svůj model“ se dá vysledovat k jedné z těchto příčin:

• Předčasné načítání. Volání výsledného URL nebo čtení polí modelu dříve, než je status ve stavu SUCCEEDED. To je zdaleka nejčastější příčina.

• Expirované assety. Příliš dlouhé čekání po SUCCEEDED před stažením – výsledná URL přestanou fungovat po uplynutí doby uchování pro daný typ úlohy.

• Použití zastaralého nebo chybného ID úlohy – například opakované použití ID z předchozího, nesouvisejícího požadavku.

• Pokládání FAILED za přechodný stav a pokračování v dotazování úlohy, která již selhala, místo opětovného odeslání požadavku.

• Síťové problémy/timeouty mezi vaším serverem a Meshy, které jsou mylně vykládány jako problém s generováním.

Pokud generování nesplní vaše očekávání, nebo požadavek úplně selže, mějte na paměti následující:

• Meshy API v současnosti nepodporuje opakování existující úlohy na místě – pro nový pokus odešlete nový požadavek na generování, který bude normálně spotřebovávat kredity.

• U přechodných síťových chyb při volání API (timeouty, odpovědi 5xx) je rozumné před opětovným odesláním požadavku použít krátké exponenciální čekání (backoff).

• U samotného dotazování opakujte volání „get task“ při přechodných síťových chybách, ale nepovažujte jediné neúspěšné dotazování za selhání generování – věřte poli status až po úspěšné odpovědi.

• Pokud potřebujete vestavěnou funkci opakování pro generování, obraťte se na obchodní tým Meshy ohledně možností enterprise plánu.

K tomu téměř vždy dochází, protože se kód snaží číst výsledek dříve, než je úloha dokončena. Před načtením URL modelu vždy ověřte, že status je SUCCEEDED (a progress je 100).

Dotazování se snadněji nastavuje a je vhodné pro skripty s nízkým objemem nebo jednorázové skripty. Webhooky jsou lepší pro produkční integrace s mnoha souběžnými úlohami, protože se vyhínají zbytečným opakovaným požadavkům a okamžitě vás upozorní na dokončení úlohy.

Zpracujte jej idempotentně – zkontrolujte id úlohy proti tomu, co jste již zpracovali, a pokud již bylo zpracováno, přeskočte opakované zpracování.

Přejděte na dotazování úlohy přímo podle id. Zároveň ověřte, že váš endpoint je veřejně dostupný přes HTTPS a rychle vrací odpověď 2xx, protože pomalé či nedostupné endpointy mohou způsobovat problémy s doručením.

V současnosti ne – musíte odeslat nový požadavek na generování, který normálně spotřebuje kredity. Pokud potřebujete vestavěnou podporu opakování, obraťte se na obchodní oddělení ohledně enterprise možností.

Výsledné soubory jsou na serverech Meshy uchovávány pouze omezenou dobu po dokončení úlohy, proto si výstupy stáhněte do svého vlastního úložiště co nejdříve po úspěšném dokončení úlohy, místo abyste čekali.

• Proč se mi konzistentně objevují chyby při načítání modelů z výsledku generování pomocí API?