Hoppa till huvudinnehåll
Huvudfunktionen för Maestro API för uppgiftsfrågor är att, via det uppgifts-ID som returneras av Maestro API för videogenerering (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 i application/json hä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 i application/json här.
Request Body inkluderar:

Kodexempel

Motsvarande CURL-kod är följande:
Motsvarande Python-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 (arrayen variants innehåller en färdig video):
Fältbeskrivningarna för svaret är följande:
  • id: ID:t för denna videouppgift, som används för att unikt identifiera videogenereringsuppgiften.
  • status: Uppgiftsstatus. Värdet är pending → planning → producing → succeeded (eller failed). Huruvida uppgiften är klar avgörs av den översta status.
  • 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. stage och message återspeglar AI-regissörens senaste förloppshändelse (därför kan stage efter slutförande fortfarande vara den sista körningsfasen, till exempel producing) 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, inklusive lang, aspect, title, output_url (nedladdningsadress för den färdiga videon) med mera.
    • data.project: Resultatet för hela projektet, inklusive tarball_url (projektpaket) och outputs (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 in action: 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:
Fälten i returresultatet beskrivs nedan:
  • count: Det totala antalet uppgifter som är synliga för den aktuellt inloggade exekveraren, opåverkat av tidsvillkor eller limit.
  • items: En uppgiftsarray filtrerad efter tidsvillkor och limit, 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 kommer status 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