POST /maestro/videos), fråga efter uppgiftens körstatus och slutresultat.
Detta dokument kommer att i detalj introducera integrationsanvisningarna för Maestro API för uppgiftsfrågor. Eftersom videogenerering är en asynkron uppgift behöver du efter inskickning använda detta gränssnitt för att hämta framsteg och färdig video genom polling, polling är gratis och förbrukar inga poäng.
POST https://api.acedata.cloud/maestro/tasks
Ansökningsprocess
För att använda Maestro API för uppgiftsfrågor ska du först hämta din API Token från Ace Data Cloud-konsolen och spara den för senare användning.
Om du ännu inte har loggat in eller registrerat dig omdirigeras du automatiskt till inloggningssidan för att registrera och logga in, och återvänder automatiskt till den aktuella sidan efter slutförandet.
En API Token kan anropa alla plattformens tjänster, utan att behöva ansöka separat för varje tjänst. Vid första ansökan får du en gratis kvot för kostnadsfri testning; när kvoten är otillräcklig kan du fylla på det gemensamma saldot i konsolen.
📘 Fullständig dokumentation: Maestro API för uppgiftsfrågor →
Fråga efter en enskild uppgift
För hur man skapar en videouppgift, se dokumentet Maestro API för videogenerering. Vi använder ett av de uppgifts-ID:n som returneras av det som exempel:f57e99c4f60f4373a15517742ce2357d, för att demonstrera hur man frågar efter dess status och resultat.
Ställ in begärandehuvuden och begärandetext
Request Headers inkluderar:accept: anger att JSON-formaterade svar ska tas emot, fyll iapplication/jsonhär.authorization: nyckeln för att anropa API:t, kan väljas direkt från rullgardinsmenyn efter ansökan.content-type: formatet för begärandetexten, fyll iapplication/jsonhär.
Kodexempel
Motsvarande CURL-kod är följande:Exempel på svar
Efter att begäran har lyckats returnerar API:t status och resultat för videouppgiften. Ett exempel på svaret när uppgiften är klar visas nedan (arrayenvariants innehåller en färdig video):
id: ID:t för denna videouppgift, som används för att unikt identifiera videogenereringsuppgiften.status: Uppgiftsstatus. Värdet ärpending → planning → producing → succeeded(ellerfailed). Huruvida uppgiften är klar avgörs av den överstastatus.elapsed: Förfluten tid för uppgiften (sekunder).progress: Progressobjekt på översta nivån.percent(0–100) är 100 när uppgiften har slutförts.stageochmessageåterspeglar AI-regissörens senaste förloppshändelse (därför kanstageefter slutförande fortfarande vara den sista körningsfasen, till exempelproducing) och kan användas direkt för att visa en förloppsindikator.request: Begärandetexten när uppgiften startades.response: Uppgiftens svarsmeddelande.success: Anger om uppgiften lyckades.data.variants: Innehåller ett objekt för en färdig video på det valda språket, inklusivelang,aspect,title,output_url(nedladdningsadress för den färdiga videon) med mera.data.project: Resultatet för hela projektet, inklusivetarball_url(projektpaket) ochoutputs(länk till den färdiga videon).data.progress: En array med förloppshändelser som läggs till per fas (append-only-logg), som kan användas för att visa detaljerade förlopp i realtid.
created_at: Tidpunkt då uppgiften skapades, Unix-tidsstämpel (sekunder).started_at: Tidpunkt då uppgiften började köras, Unix-tidsstämpel (sekunder). Är null om uppgiften ännu inte har startat.finished_at: tidpunkt då uppgiften slutfördes, Unix-tidsstämpel (sekunder). null om uppgiften inte har slutförts.
Fråga efter historiklista
Genom att skicka inaction: retrieve_batch kan du hämta de senaste uppgifterna för den för närvarande inloggade utföraren (sorterade i fallande ordning efter skapandetid), vilket kan användas för listsidan ”Mina videor”. Historiklistan är isolerad efter inloggningsidentitet.
Request Body inkluderar:
Kodexempel
Motsvarande CURL-kod är följande:Exempel på svar
När begäran har lyckats returnerar API:et den aktuella användarens historiska uppgiftslista:count: Det totala antalet uppgifter som är synliga för den aktuellt inloggade exekveraren, opåverkat av tidsvillkor ellerlimit.items: En uppgiftsarray filtrerad efter tidsvillkor ochlimit, sorterad i omvänd kronologisk ordning efter skapandetid; formatet för varje element är samma som returresultatet för ”Fråga efter en enskild uppgift”.
Rekommendationer för polling
Eftersom videoproduktion tar lång tid kommerstatus att gå igenom pending → planning → producing → succeeded (eller failed). Det rekommenderas att polla en gång var 5–10:e sekund tills status ändras till succeeded eller failed. Den översta nivån progress.percent kan användas för att visa en förloppsindikator i realtid. Polling av detta API är kostnadsfri och förbrukar inga poäng.
Felhantering
När API:et anropas returnerar API:et motsvarande felkod och information om ett fel uppstår. Till exempel:401 invalid_token: Obehörig, ogiltig eller saknad auktoriseringstoken.404 not_found: Uppgiften hittades inte, det angivna task_id finns inte.429 too_many_requests: För många begäranden, du har överskridit hastighetsgränsen.500 api_error: Internt serverfel, något gick fel på servern.
Exempel på felsvar
Slutsats
Genom detta dokument har du lärt dig hur du använder Maestro API för uppgiftsfrågor för att fråga efter status och resultat för en enskild uppgift, samt hur du hämtar den aktuella användarens historiska uppgiftslista. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda detta API. Om du har några frågor, kontakta gärna vårt tekniska supportteam när som helst.Relaterade gränssnitt
- Integreringsguide för Maestro API för videogenerering: Producera automatiskt en färdig video med undertexter med hjälp av en naturlig språkprompt i en mening, returnera
task_idefter inskickning och polla sedan resultatet med detta gränssnitt.

