prompt för att beskriva videon du vill ha (och kan valfritt bifoga referensbilder / videor / ljud med file_urls), så kommer en huvudlös ”AI-regissör” automatiskt att slutföra ämnesval, manusförfattande, bildgenerering, röstpålägg, bakgrundsmusik, sammansättning och rendering, och slutligen producera en färdig video med undertexter och ladda upp den till CDN.
Detta dokument introducerar integrationsguiden för Maestro API för videogenerering i detalj, för att hjälpa dig att snabbt integrera och fullt ut använda API:ets möjligheter.
Detta är ett asynkront uppgifts-gränssnitt: efter inskickning returneras task_id omedelbart, och resultatet hämtas sedan genom polling via Maestro API för uppgiftsfrågor (POST /maestro/tasks) (polling är gratis och debiteras inte). För att fortsätta iterera på en befintlig video kan du använda action: remix / edit / extend tillsammans med ref_task_id.
Ansökningsprocess
För att använda Maestro API för videogenerering ska du först hämta din API-token i 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 där du uppmanas att registrera dig och logga in. När detta är klart återgår du automatiskt till den aktuella sidan.
En API-token kan anropa alla plattformens tjänster, utan att du behöver ansöka separat för varje tjänst. Vid första ansökan får du gratis kredit för att testa utan kostnad; om krediten inte räcker till kan du fylla på det gemensamma saldot i konsolen.
📘 Fullständig dokumentation: Maestro API för videogenerering →
Grundläggande användning
POST https://api.acedata.cloud/maestro/videos
För den mest grundläggande användningen behöver du bara ange en prompt på naturligt språk. AI-regissören avgör automatiskt manus, bild, berättarröst och redigering. Här går vi först igenom de begärandehuvuden och den begärandetext som behöver anges.
Begärandehuvuden omfattar:
accept: vilket format svaret ska ha. Angeapplication/jsonhär, det vill säga JSON-format.authorization: nyckeln för att anropa API:et. Efter ansökan kan den väljas direkt i rullgardinsmenyn.content-type: formatet för begärandetexten. Angeapplication/jsonhär.
prompt: beskriv videon som ska skapas på naturligt språk (tema, vad som ska visas, stil och målgrupp).langs: array med språk för den färdiga videon. Skicka endast ett språk åt gången, till exempel["zh-cn"]. Standardvärdet är["zh-cn"].aspect: bildförhållande,9:16(standard) /16:9/1:1.duration: önskad längd (sekunder), standardvärdet är 30.
Nedan visas ett konkret exempel. Anta att vi vill generera en 20 sekunder lång populärvetenskaplig kortvideo på kinesiska i stående format. Motsvarande CURL-kod är följande:
success: Om uppgiften har skickats in korrekt.task_id: ID:t för denna videogenereringsuppgift. Använd det senare för att hämta resultat genom polling via Maestro API för uppgiftsfrågor.trace_id: Spårnings-ID:t för denna begäran. Om problem uppstår kan det lämnas till teknisk support för felsökning.
task_id och väntar inte på att videorenderingen ska slutföras. Använd sedan task_id för att polla resultatet. Se avsnittet ”Hämta resultat” för mer information.
Ange videotyp och stil (scenario / style)
Närscenario inte skickas avgör AI automatiskt (motsvarar auto); om du vill låsa videon till en viss typ skickar du det explicit. Till exempel kan du ange följande innehåll för att skapa ett vertikalt kortdrama:
scenario:videotyp, anges här somdrama(kortdrama med karaktärer + dialog).style:visuell stil, anges här somcinematic(filmisk känsla).
- Berättande kortfilm:
scenario: "narrated"。 - Automatiska undertexter:
scenario: "captions",källvideon måste skickas medfile_urls。 - Digital människa / talvideo:
scenario: "avatar",ett porträttfoto måste skickas medfile_urls。 - Kortdrama:
scenario: "drama"(karaktärer + dialog)。 styleär en förinställning för visuell stil(t.ex.modern/neon/luxury),ändrar inte typen utan påverkar endast intrycket。voiceanvänds för att ange berättarröstens klangfärg(t.ex.warm-female/deep-male),är oberoende av språk och fungerar mellan språk。
task_id returneras också omedelbart.
Språk för färdig video
En uppgift levererar endast en färdig video på ett språk.langs får endast innehålla en språkkod, till exempel ["zh-cn"] eller ["en"]; om flera språk skickas returneras 400. Om du behöver videor på olika språk ska du skapa separata uppgifter. Språkvalet ändrar inte priset per sekund.
Iterera på befintlig video (remix / edit / extend)
Skicka inaction och ref_task_id från den föregående uppgiften för att göra inkrementella ändringar baserat på originalprojektet (t.ex. ”ändra titeln i scen 2”, ”byt röst”, ”gör helheten mörkare”). Små ändringar går snabbt, medan stora ändringar görs om:
remix:nytolkning baserad på originalvideons struktur(behåller temat och justerar uttrycket)。edit:finjustering av angivna delar(t.ex. byt titel, byt röst, färgkorrigering)。extend:utökar innehållet baserat på originalvideon。
task_id returneras omedelbart, använd det för polling för att hämta den itererade färdiga videon.
Hämta resultat
Eftersom videoproduktion tar relativt lång tid returnerar detta gränssnitttask_id omedelbart efter inskickning, och du behöver använda det för att polla resultaten via Maestro API för uppgiftsfrågor:
variants). status går igenom pending → planning → producing → succeeded (eller failed), polling är gratis och förbrukar inga poäng. Se Integrationsguide för Maestro API för uppgiftsfrågor för det fullständiga svarsformatet och frågor om historiklistor.
Fakturering
Efter att uppgiften har lyckats debiteras den faktiska längden på den levererade färdiga videon, och misslyckanden debiteras inte. Faktureringstiden beräknas i hela sekunder och överstiger inte den begärda längden; om längden på den färdiga videon inte kan läsas används den begärda längden som reserv. Att skicka in själva uppgiften debiteras inte separat, och polling via/maestro/tasks är gratis.
Felhantering
Vid anrop av API:et returnerar API:et motsvarande felkod och information om ett fel uppstår. Till exempel:400 invalid_request:Felaktig begäran, eventuellt på grund av en saknadprompteller ogiltiga parametrar.401 invalid_token:Obehörig, ogiltig eller saknad auktoriseringstoken.403 forbidden:Förbjuden, otillräckligt saldo eller otillräcklig åtkomst.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 videogenerering: med endast en naturlig språk-prompt kan du automatiskt slutföra manus, material, röstpålägg, bakgrundsmusik, klippning, undertexter och rendering av färdig video, och det stöder även angivelse av videotyp, stil, röstklang, språk för färdig video samt iteration på befintliga videor. Vi hoppas att detta dokument hjälper dig att integrera och använda detta API bättre. Om du har några frågor, kontakta gärna vårt tekniska supportteam när som helst.
Relaterade gränssnitt
- Integrationsguide för Maestro API för uppgiftsfrågor:använd
task_idsom returneras avPOST /maestro/videosför att fråga uppgiftsstatus och resultat, eller hämta historiska uppgiftslistor(polling är gratis)。

