Meshy API Webhooks jämfört med Polling: När resultaten är klara

Meshy API:s genereringsuppgifter (Text to 3D, Image to 3D, Rigging med flera) körs asynkront — du skickar in en uppgift och behöver sedan ta reda på när den är klar innan du hämtar resultatet. Den här artikeln förklarar uppgiftens livscykel och de två stödda sätten att veta när en uppgift är klar: pollning och webhooks — plus hur du undviker det vanligaste problemet "fel vid hämtning av modellen".

Varje genereringsuppgift går igenom ett litet antal tillstånd, som returneras i uppgiftsobjektets status-fält:

• PENDING — uppgiften har kölagts men bearbetningen har inte påbörjats än.

• IN_PROGRESS — uppgiften bearbetas aktivt. Fältet progress (0-100) ökar i takt med att arbetet framskrider.

• SUCCEEDED — uppgiften avslutades och progress är 100. Resultat-URL:er (modellfiler, texturer, förhandsvisningar) är nu tillgängliga i svaret.

• FAILED — uppgiften kunde inte slutföras. Krediter för misslyckade uppgifter återbetalas automatiskt.

• CANCELED — uppgiften avbröts innan den slutfördes.

Den viktigaste regeln när du integrerar med API:et är: försök aldrig hämta eller använda resultat-URL:er förrän uppgiftens status är SUCCEEDED. Att läsa resultat medan en uppgift fortfarande är PENDING eller IN_PROGRESS är den vanligaste orsaken till rapporter om "fel vid hämtning av modellen".

Pollning innebär att man upprepade gånger anropar "get task"-endpunkten för sitt uppgifts-ID tills den når ett sluttillstånd (SUCCEEDED, FAILED eller CANCELED). En enkel pollningsslinga ser ut så här:

• Skicka genereringsbegäran och spara det returnerade uppgifts-id:et.

• Anropa motsvarande "retrieve task"-endpunkt (till exempel endpunkten för Text to 3D- eller Image to 3D-uppgift via id) med ett intervall — några sekunder är typiskt.

• Kontrollera status-fältet i varje svar. Fortsätt polla medan det är PENDING eller IN_PROGRESS.

• Sluta polla så snart status är SUCCEEDED (läs resultat-URL:erna), FAILED eller CANCELED.

• Lägg till en rimlig timeout/max-antal-försök-gräns i din klient så att en fastnat uppgift inte pollas i evighet.

Pollning är enkelt och fungerar bra för skript, batchjobb och integrationer med låg volym. För integrationer med hög volym eller latenskänslighet passar en webhook oftast bättre.

Istället för att upprepade gånger fråga "är den klar än?" kan du be Meshy att meddela din server i samma stund som en uppgift slutförs. För att använda webhooks:

• Konfigurera en webhook-URL (callback) som Meshy kan nå — denna ställs vanligtvis in på konto-/API-inställningsnivå eller skickas som en parameter i genereringsbegäran, beroende på endpunkten.

• Se till att din endpunkt är publikt nåbar över HTTPS och svarar snabbt (returnera en 2xx-status omedelbart och bearbeta sedan nyttolasten asynkront).

• När uppgiften når ett sluttillstånd skickar Meshy en nyttolast till din endpunkt som innehåller uppgiftens id och dess slutgiltiga status.

• Vid mottagning, slå upp hela uppgiftsdetaljerna via id genom API:et istället för att enbart lita på webhook-brödtexten, för att säkerställa att du har det auktoritativa och uppdaterade resultatet.

Webhooks minskar onödiga API-anrop och ger dig nästan omedelbar avisering, men du bör ändå behålla en periodisk pollning som reservlösning för uppgifter där en webhook-leverans kan missas eller försenas (t.ex. på grund av ett tillfälligt nätverksproblem på din sida).

Oavsett om du använder pollning eller webhooks bör din kod för resultatbearbetning vara idempotent — säker att köra mer än en gång för samma uppgift utan biverkningar. Detta är viktigt eftersom:

• En webhook kan levereras mer än en gång för samma uppgift (återförsök på avsändarsidan, nätverksdubbletter osv.).

• En pollningsslinga och en webhook-hanterare kan båda försöka bearbeta samma slutförda uppgift om båda körs.

För att förbli idempotent, basera din bearbetningslogik på uppgiftens id — kontrollera till exempel om du redan har lagrat/laddat ner resultat för det id:et innan du gör det igen, och gör "markera som bearbetad" till ett enda atomärt steg i din egen databas.

Ett svar med "status": "SUCCEEDED" och "progress": 100 är den enda signal som garanterar att resultatnyttolasten (modell-URL:er, texturer, miniatyrer) är komplett och säker att använda. Konkret, i din kod:

• Verifiera status === "SUCCEEDED" innan du läser något ur fälten result/modell-URL.

• Lita inte enbart på progress — kontrollera alltid status också, eftersom progress kort kan visa höga värden innan uppgiften är helt slutförd.

• Ladda ner resultatfilerna snabbt när SUCCEEDED uppnåtts — genererade tillgångar sparas bara på Meshys servrar under en begränsad tid, varefter URL:erna inte längre fungerar.

De flesta rapporter om "jag kan inte hämta min modell" spåras till en av dessa orsaker:

• Hämtar för tidigt. Att anropa resultat-URL:en, eller läsa modellfälten, innan status är SUCCEEDED. Detta är den klart vanligaste orsaken.

• Utgångna tillgångar. Att vänta för länge efter SUCCEEDED med att ladda ner — resultat-URL:er slutar fungera efter att lagringsfönstret för den uppgiftstypen har passerat.

• Använda ett inaktuellt eller felaktigt uppgifts-ID — till exempel att återanvända ett ID från en tidigare, orelaterade begäran.

• Behandla FAILED som ett tillfälligt tillstånd och fortsätta polla en uppgift som redan har misslyckats istället för att skicka in den igen.

• Nätverks-/timeout-problem mellan din server och Meshy som feltolkas som ett genereringsproblem.

Om en generering inte möter dina förväntningar, eller om en begäran misslyckas helt, tänk på följande:

• Meshy API stöder för närvarande inte återförsök av en befintlig uppgift på plats — för att försöka igen, skicka in en ny genereringsbegäran, vilken förbrukar krediter som vanligt.

• Vid tillfälliga nätverksfel vid API-anrop (timeouts, 5xx-svar) är en kort exponentiell backoff innan begäran skickas igen rimligt.

• För pollningen själv, försök igen med "get task"-anropet vid tillfälliga nätverksfel, men behanda inte ett enda misslyckat poll som ett genereringsfel — lita bara på status-fältet när du får ett lyckat svar.

• Om du behöver inbyggd återförsöksfunktion för genereringar, kontakta Meshys säljteam om alternativ för företagsplaner.

Detta händer nästan alltid för att koden försöker läsa resultatet innan uppgiften är klar. Bekräfta alltid att status är SUCCEEDED (och att progress är 100) innan du hämtar modell-URL:er.

Pollning är enklare att konfigurera och fungerar bra för låg volym eller engångsskript. Webhooks är bättre för produktionsintegrationer med många samtidiga uppgifter, eftersom de undviker onödiga upprepade förfrågningar och meddelar dig omedelbart när en uppgift slutförs.

Hantera det idempotent — kontrollera uppgiftens id mot vad du redan har bearbetat, och hoppa över ny bearbetning om det redan har hanterats.

Falla tillbaka till att polla uppgiften direkt via id. Bekräfta också att din endpunkt är publikt nåbar över HTTPS och returnerar ett snabbt 2xx-svar, eftersom långsamma eller onåbara endpunkter kan orsaka leveransproblem.

Inte för närvarande — du behöver skicka in en ny genereringsbegäran, vilken förbrukar krediter som vanligt. Kontakta säljteamet om företagsalternativ om du behöver inbyggt stöd för återförsök.

Resultatfiler sparas bara på Meshys servrar under en begränsad tid efter att en uppgift slutförts, så ladda ner utdata till din egen lagring så snart uppgiften lyckas istället för att vänta.

• Varför får jag konsekvent fel när jag hämtar modellerna från genereringsresultat via API?