Meshy API Webhooky vs. polling: kdy jsou výsledky připraveny

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

Každá úloha generování prochází malou sadou stavů, které se vracejí v poli status objektu úlohy:

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

• IN_PROGRESS — úloha se aktivně zpracovává. Pole progress (0–100) se s dokončováním práce zvyšuje.

• SUCCEEDED — úloha byla úspěšně dokončena a progress je 100. URL adresy výsledků (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 se automaticky vracejí.

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

Jedno nejdůležitější pravidlo při integraci s API: nikdy se nepokoušejte načíst nebo použít URL adresy výsledků, dokud status úlohy není SUCCEEDED. Čtení výsledků, zatímco je úloha stále ve stavu PENDING nebo IN_PROGRESS, je nejčastější příčinou hlášení „errors retrieving the model“.

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

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

• V intervalu volejte odpovídající endpoint „retrieve task“ (například endpoint pro získání úlohy Text to 3D nebo Image to 3D podle ID) — typicky několik sekund.

• U každé odpovědi zkontrolujte pole status. Pokračujte v pollingu, dokud je PENDING nebo IN_PROGRESS.

• Přestaňte pollovat, jakmile je status SUCCEEDED (přečtěte URL výsledků), FAILED nebo CANCELED.

• Přidejte do klienta rozumnou pojistku pro timeout/maximální počet pokusů, aby zaseknutá úloha nepollovala donekonečna.

Polling je jednoduchý a dobře funguje pro skripty, dávkové úlohy a integrace s nízkým objemem. Pro integrace s vysokým objemem nebo citlivé na latenci je obvykle vhodnější webhook.

Namísto opakovaného dotazování „už je to hotové?“ můžete Meshy požádat, aby váš server upozornila ve chvíli, kdy se úloha dokončí. Pro použití webhooků:

• Nakonfigurujte URL webhooku (callback), kterou Meshy dokáže kontaktovat — obvykle se nastavuje na úrovni nastavení účtu/API nebo se předává jako parametr požadavku na generování, v závislosti na koncovém bodu.

• Zajistěte, aby byl váš koncový bod veřejně dostupný přes HTTPS a rychle odpovídal (okamžitě vraťte stav 2xx a poté zpracujte payload asynchronně).

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

• Po přijetí si přes API vyhledejte úplné podrobnosti úlohy podle id, místo abyste věřili samotnému tělu webhooku, abyste měli zaručeně autoritativní a aktuální výsledek.

Webhooky snižují počet zbytečných volání API a poskytují téměř okamžitá oznámení, ale u úloh, kde může být doručení webhooku zmeškáno nebo zpožděno (např. kvůli přechodnému síťovému problému na vaší straně), byste si měli stále ponechat pravidelné dotazování (polling) jako záložní mechanismus.

Ať už používáte polling, nebo webhooky, váš kód pro zpracování výsledků by měl být idempotentní — bezpečný ke spuštění více než jednou pro stejnou úlohu bez vedlejších účinků. To je důležité, protože:

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

• Smyčka pollingu a obslužná rutina webhooku se mohou obě snažit zpracovat stejnou dokončenou úlohu, pokud běží obě.

Abyste zůstali idempotentní, odvíjejte svou logiku zpracování od id úlohy — například před dalším zpracováním zkontrolujte, zda jste už výsledky pro toto id uložili/stáhli, a „označit jako zpracované“ udělejte jediným atomickým krokem ve své vlastní databázi.

Odpověď s "status": "SUCCEEDED" a "progress": 100 je jediným signálem, který zaručuje, že datová část výsledku (URL modelů, textury, náhledy) je kompletní a bezpečná k použití. Konkrétně ve vašem kódu:

• Před čtením jakýchkoli hodnot z polí result/URL modelu ověřte, že status === "SUCCEEDED".

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

• Stáhněte soubory výsledku včas, jakmile je stav SUCCEEDED — vygenerované prostředky jsou na serverech Meshy uchovávány pouze omezenou dobu, po jejímž uplynutí URL přestanou fungovat.

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

• Příliš brzké načítání. Volání URL výsledku nebo čtení polí modelu předtím, než je status SUCCEEDED. To je zdaleka nejčastější příčina.

• Expirované prostředky. Čekání příliš dlouho po SUCCEEDED na stažení — URL výsledků přestanou fungovat poté, co uplyne doba uchovávání pro daný typ úlohy.

• Použití zastaralého nebo nesprávného ID úlohy — například opětovné použití ID z předchozího, nesouvisejícího požadavku.

• Zacházení s FAILED jako s přechodným stavem a pokračování v dotazování úlohy, která už selhala, místo opětovného odeslání.

• Problémy se sítí/vypršením časového limitu mezi vaším serverem a Meshy, které se chybně interpretují jako problém s generováním.

Pokud generování neodpovídá vašim očekáváním 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 přímo — chcete-li to zkusit znovu, odešlete nový požadavek na generování, což standardně spotřebuje kredity.

• U přechodných síťových selhání při volání API (časové limity, odpovědi 5xx) je rozumné před opětovným odesláním požadavku zařadit krátké exponenciální zpoždění mezi pokusy.

• U samotného pollingu opakujte volání „get task“ při přechodných síťových chybách, ale jedno neúspěšné dotazování nepovažujte za selhání generování — poli status důvěřujte až poté, co obdržíte úspěšnou odpověď.

• Pokud pro generování potřebujete vestavěnou funkci opakování, obraťte se na obchodní tým Meshy a proberte možnosti podnikového plánu.

Téměř vždy se to stává proto, že se kód snaží přečíst výsledek dříve, než je úloha dokončena. Před načtením URL modelů vždy ověřte, že status je SUCCEEDED (a progress je 100).

Polling se snáze nastavuje a stačí pro malý objem nebo jednorázové skripty. Webhooky jsou vhodnější pro produkční integrace s mnoha souběžnými úlohami, protože se vyhýbají zbytečným opakovaným požadavkům a okamžitě vás upozorní, když se úloha dokončí.

Zpracujte jej idempotentně — porovnejte id úlohy s tím, co jste už zpracovali, a pokud už byl zpracován, přeskočte opakované zpracování.

Přejděte zpět k přímému pollingu úlohy podle id. Také ověřte, že váš endpoint je veřejně dostupný přes HTTPS a vrací rychlou odpověď 2xx, protože pomalé nebo nedostupné endpointy mohou způsobit problémy s doručením.

Momentálně ne — musíte odeslat nový požadavek na generování, který standardně spotřebovává kredity. Pokud potřebujete vestavěnou podporu opakování, obraťte se na obchodní oddělení ohledně podnikových možností.

Soubory výsledků jsou na serverech Meshy uchovávány pouze omezenou dobu po dokončení úlohy, proto výstupy stáhněte do vlastního úložiště hned, jak úloha uspěje, a nečekejte.