Hoppa till huvudinnehåll
Maestro är ett Agent-nativt videoproduktionsgränssnitt: du använder en naturlig språklig 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. Ange application/json hä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. Ange application/json här.
Begärandetexten omfattar huvudsakligen:
  • 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.
Alla fält i begärandetexten visas i tabellen nedan: 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:
Motsvarande Python-kod är följande:
Klicka på Kör så ser du att ett resultat returneras omedelbart, enligt följande:
Fältbeskrivningarna för svaret ä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.
Eftersom videoproduktion tar lång tid returnerar gränssnittet här omedelbart 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är scenario 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 som drama (kortdrama med karaktärer + dialog).
  • style:visuell stil, anges här som cinematic (filmisk känsla).
Exempel på ifylld CURL-kod är följande:
Vanliga kombinationer:
  • Berättande kortfilm:scenario: "narrated"。
  • Automatiska undertexter:scenario: "captions",källvideon måste skickas med file_urls。
  • Digital människa / talvideo:scenario: "avatar",ett porträttfoto måste skickas med file_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。
  • voice anvä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。
Returresultatet är detsamma som i ”Grundläggande användning”, och 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 in action 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。
Returresultatet är också att ett nytt 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änssnitt task_id omedelbart efter inskickning, och du behöver använda det för att polla resultaten via Maestro API för uppgiftsfrågor:
När uppgiften är klar returneras information om en färdig video (i arrayen 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.
Alla scenarier, åtgärder och språk använder samma pris, utan scenariomultiplikator eller språkpåslag. Varje uppgift levererar endast en färdig video på ett språk. Begärd mållängd stöder 5–300 sekunder, med enhetlig utdata i 1080p / 30fps.

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 saknad prompt eller 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