Meshy API-webhooks vs pollning: när resultaten är klara

Meshy API-genereringsuppgifter (Text to 3D, Image to 3D, Rigging med flera) körs asynkront – du skickar in en uppgift och måste 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å sätt som stöds för att veta när en uppgift har slutförts: pollning och webhooks – samt hur du undviker det vanligaste problemet med ”fel vid hämtning av modellen”.

Varje genereringsuppgift går igenom en liten uppsättning tillstånd, som returneras i fältet status i uppgiftsobjektet:

• PENDING — uppgiften har köats men bearbetningen har inte börjat än.

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

• SUCCEEDED — uppgiften slutfördes framgångsrikt 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 enskilt viktigaste regeln när du integrerar mot API:et: 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 du upprepade gånger anropar slutpunkten ”get task” för ditt uppgifts-ID tills uppgiften når ett slutligt tillstånd (SUCCEEDED, FAILED eller CANCELED). En enkel pollningsloop ser ut så här:

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

• Anropa motsvarande slutpunkt för att hämta uppgiften (”retrieve task”, till exempel slutpunkten för Text to 3D- eller Image to 3D-uppgift via ID) med ett intervall – några sekunder är vanligt.

• Kontrollera fältet status i varje svar. Fortsätt polla så länge 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 tidsgräns eller gräns för maximalt antal försök i klienten så att en fastnad uppgift inte pollas för evigt.

Pollning är enkelt och fungerar bra för skript, batchjobb och integrationer med låg volym. För integrationer med hög volym eller krav på låg latens passar webhooks vanligtvis bättre.

I stället för att upprepat fråga "är det klart än?" kan du låta Meshy meddela din server i samma ögonblick som en uppgift slutförs. Så här använder du webhooks:

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

• Se till att din slutpunkt är offentligt åtkomlig via HTTPS och svarar snabbt (returnera en 2xx-status direkt och bearbeta sedan nyttolasten asynkront).

• När uppgiften når ett slutligt tillstånd skickar Meshy en nyttolast till din slutpunkt som innehåller uppgiftens id och dess slutliga status.

• När du tar emot den, slå upp uppgiftens fullständiga detaljer via id med API:et i stället för att lita på enbart webhookens innehåll, så att du säkerställer att du har det auktoritativa och aktuella resultatet.

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

Oavsett om du använder pollning eller webhooks bör din kod för resultathantering 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ätverksduplicering osv.).

• En pollningsloop 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 bör du basera din bearbetningslogik på uppgiftens id – kontrollera till exempel om du redan har sparat/laddat ner resultat för samma id innan du gör det igen, och gör ”markera som bearbetad” till ett enda atomiskt steg i din egen databas.

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

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

• Förlita dig inte enbart på progress – kontrollera alltid status också, eftersom progress kortvarigt kan visa höga värden innan uppgiften är helt slutförd.

• Ladda ner resultatfiler omgående när status är SUCCEEDED – genererade tillgångar behålls bara på Meshys servrar under en begränsad tid, varefter URL:erna inte längre kommer att fungera.

De flesta rapporter om "jag kan inte hämta min modell" beror på en av följande orsaker:

• Hämtar för tidigt. Anropar resultat-URL:en eller läser modellfälten innan status är SUCCEEDED. Detta är den absolut vanligaste orsaken.

• Utgångna tillgångar. Väntar för länge efter SUCCEEDED med att ladda ner – resultat-URL:er slutar fungera efter att kvarhållningsfönstret för den uppgiftstypen har passerat.

• Använder ett inaktuellt eller felaktigt uppgifts-ID – till exempel återanvänder ett ID från en tidigare, orelaterad begäran.

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

• Nätverks-/timeoutproblem mellan din server och Meshy som misstolkas som ett genereringsproblem.

Om en generering inte motsvarar dina förväntningar, eller om en begäran misslyckas helt, bör du tänka på följande:

• Meshy API stöder för närvarande inte att göra om en befintlig uppgift på plats – för att försöka igen skickar du en ny genereringsbegäran, vilket förbrukar krediter som vanligt.

• Vid tillfälliga nätverksfel när du anropar API:et (timeouts, 5xx-svar) är en kort exponentiell backoff innan du skickar begäran igen rimlig.

• För själva pollningen: försök igen med anropet "get task" vid tillfälliga nätverksfel, men behandla inte en enskild misslyckad pollning som ett genereringsfel – lita bara på fältet status när du får ett lyckat svar.

• Om du behöver inbyggd återförsöksfunktion för genereringar kan du kontakta Meshys säljteam för att höra om alternativ för enterprise-planen.

Detta beror nästan alltid på att koden försöker läsa resultatet innan uppgiften har slutförts. 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ågvolym 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 direkt när en uppgift har slutförts.

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

Fall tillbaka på att polla uppgiften direkt via id. Bekräfta också att din slutpunkt är offentligt åtkomlig över HTTPS och returnerar ett snabbt 2xx-svar, eftersom långsamma eller otillgängliga slutpunkter kan orsaka leveransproblem.

Inte för närvarande – du behöver skicka en ny genereringsförfrågan, vilket förbrukar krediter som vanligt. Kontakta försäljning om företagsalternativ om du behöver inbyggt stöd för återförsök.

Resultatfiler finns bara kvar på Meshys servrar under en begränsad tid efter att en uppgift har slutförts, så ladda ner utdata till din egen lagring så snart uppgiften har lyckats i stället för att vänta.