> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Maestro Video-Generierungs-API Integrationsanleitung > Maestro AI Video Studio API guide - Ace Data Cloud Maestro ist eine **Agent-native** Video-Produktionsschnittstelle: Sie beschreiben das gewünschte Video mit einem natürlichen Sprach-`prompt` (optional mit `file_urls` zur Bereitstellung von Referenzbildern / Videos / Audios), und ein kopfloser „AI-Regisseur“ erledigt automatisch die Themenwahl, das Schreiben des Skripts, die Erstellung der Bilder, die Vertonung, die Musik, die Komposition und das Rendering, um schließlich ein fertiges Video mit Untertiteln zu produzieren und es auf das CDN hochzuladen. Dieser Artikel wird die Integrationsanleitung der Maestro Video-Generierungs-API im Detail vorstellen, um Ihnen zu helfen, diese API schnell zu integrieren und ihre Fähigkeiten voll auszuschöpfen. Dies ist eine **asynchrone Aufgaben**-Schnittstelle: Nach der Einreichung wird sofort eine `task_id` zurückgegeben, und anschließend können Sie über die [Maestro Aufgabenabfrage-API](/de/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) die Ergebnisse abfragen (Abfragen sind kostenlos und werden nicht berechnet). Um auf einem vorhandenen Video weiterzuarbeiten, können Sie `action: remix` / `edit` / `extend` zusammen mit `ref_task_id` verwenden. ## Antragsprozess Um die Maestro Video-Generierungs-API zu nutzen, müssen Sie zunächst im [Ace Data Cloud Dashboard](https://platform.acedata.cloud/console/applications) Ihr API-Token abrufen und für zukünftige Verwendung aufbewahren. ![](https://cdn.acedata.cloud/dvc3cg.jpg) Wenn Sie noch nicht angemeldet oder registriert sind, werden Sie automatisch zur Anmeldeseite weitergeleitet, um sich zu registrieren und anzumelden. Nach Abschluss werden Sie automatisch zur aktuellen Seite zurückgeleitet. **Ein API-Token reicht aus, um auf alle Dienste der Plattform zuzugreifen, ohne dass für jeden Dienst separat beantragt werden muss.** Bei der ersten Beantragung erhalten Sie ein kostenloses Kontingent, um die Funktionen kostenlos auszuprobieren; wenn das Kontingent erschöpft ist, können Sie im [Dashboard](https://platform.acedata.cloud/console/coin) Ihr allgemeines Guthaben aufladen. > 📘 Vollständige Dokumentation: [Maestro Video-Generierungs-API →](https://platform.acedata.cloud/documents/maestro-videos) ## Grundlegende Nutzung `POST https://api.acedata.cloud/maestro/videos` Die grundlegendste Verwendung erfordert nur die Übermittlung eines natürlichen Sprach-`prompt`, und der AI-Regisseur entscheidet automatisch über das Skript, die Bilder, die Vertonung und den Schnitt. Hier erfahren wir zunächst, welche Header und den Request-Body wir einstellen müssen. **Request Headers** umfassen: * `accept`: In welchem Format Sie die Antwort erhalten möchten, hier als `application/json`, also im JSON-Format. * `authorization`: Der Schlüssel zur API-Nutzung, den Sie nach der Beantragung direkt auswählen können. * `content-type`: Das Format des Request-Bodys, hier als `application/json`. **Request Body** umfasst hauptsächlich: * `prompt`: Beschreiben Sie das Video in natürlicher Sprache (Thema, was gezeigt werden soll, Stil, Zielgruppe). * `langs`: Array der Ausgabesprachen, wie `["zh-cn", "en"]`, standardmäßig `["zh-cn"]`. * `aspect`: Bildverhältnis, `9:16` (Standard) / `16:9` / `1:1`. * `duration`: Zielzeit (Sekunden), standardmäßig 30. Die vollständigen Felder des Request-Bodys sind in der folgenden Tabelle dargestellt: | Feld | Typ | Pflicht | Beschreibung | | - | - | - | - | | `prompt` | string | Ja | Beschreiben Sie das Video in natürlicher Sprache (Thema, was gezeigt werden soll, Stil, Zielgruppe). Skript, Bilder, Vertonung und Schnitt werden vom AI entschieden. | | `action` | string | Nein | `generate` (Standard, neues Video erstellen) / `remix` / `edit` / `extend` (Iterieren auf einem vorhandenen Video, muss mit `ref_task_id` kombiniert werden). | | `ref_task_id` | string | Nein | Muss ausgefüllt werden, wenn `action` remix / edit / extend ist: die `task_id` der historischen Aufgabe, die als Ausgangspunkt dient. | | `file_urls` | string\[] | Nein | Referenzmedien (Bilder / Videos / Audio-URLs), z. B. Produktbilder, Logos oder Materialabschnitte, die untertitelt werden sollen. | | `langs` | string\[] | Nein | Ausgabesprachen, wie `["zh-cn", "en"]`, standardmäßig `["zh-cn"]`. Die erste ist die Hauptsprache; für jede zusätzliche Sprache wird das Bild wiederverwendet, es gibt nur zusätzliche Vertonung + Rendering, **jede zusätzliche +6 Punkte**. | | `aspect` | string | Nein | `9:16` (Standard) / `16:9` / `1:1`, einheitliche Ausgabe in 1080p/30fps. | | `duration` | int | Nein | Zielzeit (Sekunden), standardmäßig 30, unterstützt **5–300 Sekunden**. Abgerechnet wird nach der tatsächlichen Videolänge, jedoch nicht mehr als die angeforderte Länge. | | `scenario` | string | Nein | Videoart: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` erfordert das Quellvideo, `avatar` erfordert ein Porträt. | | `style` | string | Nein | Voreinstellung des visuellen Stils: `auto` (Standard) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, auch Freitext als weiche Eingabe akzeptiert. Steht im Widerspruch zu `scenario`, ändert die Route nicht. | | `voice` | string | Nein | Erzählstimme (sprachunabhängig, über Sprachen hinweg verwendbar): `auto` (Standard) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`. | Hier ist ein konkretes Beispiel zur Veranschaulichung. Angenommen, wir möchten ein zweisprachiges, vertikales, 20-sekündiges Wissenschaftsvideo generieren, der entsprechende CURL-Code lautet: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点", "langs": ["zh-cn", "en"], "aspect": "9:16", "duration": 20 }' ``` Der entsprechende Python-Code lautet: ```python theme={null} import requests url = "https://api.acedata.cloud/maestro/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点", "langs": ["zh-cn", "en"], "aspect": "9:16", "duration": 20 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Wenn Sie auf Ausführen klicken, werden Sie sofort ein Ergebnis erhalten, wie folgt: ```json theme={null} { "success": true, "task_id": "f57e99c4f60f4373a15517742ce2357d", "trace_id": "70e1cb12-c619-4292-a416-90191205996b" } ``` Die Beschreibung der zurückgegebenen Felder ist wie folgt: * `success`：Ob die Aufgabe erfolgreich eingereicht wurde. * `task_id`：Die ID der aktuellen Videoerzeugungsaufgabe, die später zur Abfrage der Ergebnisse über die [Maestro Aufgabenabfrage API](/de/guides/maestro/maestro_tasks) verwendet wird. * `trace_id`：Die Verfolgungs-ID dieser Anfrage, die bei Problemen dem technischen Support zur Lokalisierung bereitgestellt werden kann. Da die Videoerstellung längere Zeit in Anspruch nimmt, gibt die Schnittstelle hier **sofort `task_id`** zurück und wartet nicht auf den Abschluss des Video-Renderings. Anschließend muss `task_id` verwendet werden, um die Ergebnisse abzufragen, siehe Abschnitt „Ergebnisse abrufen“. ## Bestimmen des Video-Typs und -Stils (scenario / style) Wenn `scenario` nicht übergeben wird, entscheidet die KI automatisch (entspricht `auto`); um das Video auf einen bestimmten Typ festzulegen, muss dies explizit übergeben werden. Zum Beispiel, um ein **Hochformat-Kurzdrama** zu erstellen, können folgende Inhalte angegeben werden: * `scenario`：Video-Typ, hier auf `drama` (Charaktere + Dialoge des Kurzdramas) gesetzt. * `style`：Visueller Stil, hier auf `cinematic` (filmische Qualität) gesetzt. Ein Beispiel für den CURL-Code sieht wie folgt aus: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "prompt": "Zwei Mitbewohner streiten sich wegen einer Katze und versöhnen sich wieder, drei Akte mit Wendungen, das Ende ist warmherzig", "scenario": "drama", "style": "cinematic", "aspect": "9:16", "duration": 40 }' ``` Häufige Kombinationen: * Erzählvideo: `scenario: "narrated"`, Lite / Standard / Pro unterstützen alle. * Automatische Untertitel: `scenario: "captions"`, erfordert `file_urls` für das Quellvideo, Lite / Standard / Pro unterstützen alle. * Digitale Menschen / Voiceover: `scenario: "avatar"`, erfordert `file_urls` für ein Porträt, Standard / Pro unterstützen. * Kurzdrama: `scenario: "drama"` (Charaktere + Dialoge), nur Pro unterstützt. * `style` ist eine visuelle Stilvorgabe (z. B. `modern` / `neon` / `luxury`), ändert den Typ nicht, beeinflusst nur die Wahrnehmung. * `voice` wird verwendet, um den Erzählton anzugeben (z. B. `warm-female` / `deep-male`), unabhängig von der Sprache, sprachübergreifend. Das Rückgabeergebnis ist identisch mit dem „Grundlegende Nutzung“, ebenfalls wird sofort `task_id` zurückgegeben. ## Mehrsprachige Ausgabe Indem mehrere Sprachen in `langs` übergeben werden, können gleichzeitig mehrsprachige Versionen erstellt werden. Die erste Sprache ist die Hauptsprache, jede zusätzliche Sprache wird **mit demselben Bildmaterial wiederverwendet**, nur die Sprachaufnahme + Rendering wird zusätzlich durchgeführt, daher **kostet jede zusätzliche Sprache nur +6 Punkte**. Beispiel: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "prompt": "Stellen Sie unser intelligentes Kundenservice-Produkt vor und heben Sie 3 Kernmerkmale hervor", "langs": ["zh-cn", "en", "ja"], "aspect": "16:9", "duration": 30 }' ``` Nach Abschluss der Aufgabe wird jede Sprache einem `variant` im Ergebnis zugeordnet (siehe [Maestro Aufgabenabfrage API](/de/guides/maestro/maestro_tasks)). ## Iteration auf bestehenden Videos (remix / edit / extend) Übergeben Sie `action` und die `ref_task_id` der letzten Aufgabe, um differenzielle Änderungen auf der Grundlage des ursprünglichen Projekts vorzunehmen (z. B. „Ändern Sie den Titel des 2. Aktes“ „Ändern Sie die Sprachaufnahme“ „Gesamtes Bild dunkler machen“). Kleine Änderungen sind schnell, große Änderungen erfordern eine Neugestaltung: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "remix", "ref_task_id": "f57e99c4f60f4373a15517742ce2357d", "prompt": "Ändern Sie den Eröffnungstitel in einen eindrucksvolleren Satz, die gesamte Farbgebung etwas dunkler" }' ``` * `remix`：Das ursprüngliche Video wird neu interpretiert (Thema beibehalten, Darstellung angepasst). * `edit`：Feinbearbeitung eines bestimmten Teils (z. B. Titel ändern, Sprachaufnahme ändern, Farbkorrektur). * `extend`：Inhalt auf der Grundlage des ursprünglichen Videos erweitern. Das Rückgabeergebnis gibt ebenfalls sofort eine neue `task_id` zurück, mit der die iterierte Endversion abgerufen werden kann. ## Ergebnisse abrufen Da die Videoerstellung längere Zeit in Anspruch nimmt, gibt diese Schnittstelle nach der Einreichung sofort `task_id` zurück, die Sie verwenden müssen, um die Ergebnisse über die [Maestro Aufgabenabfrage API](/de/guides/maestro/maestro_tasks) abzufragen: ```bash theme={null} curl -X POST 'https://api.acedata.cloud/maestro/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "f57e99c4f60f4373a15517742ce2357d" }' ``` Wenn die Aufgabe abgeschlossen ist, werden die Informationen zum Endprodukt zurückgegeben (jede Sprache entspricht einem `variant`). `status` durchläuft `pending → planning → producing → succeeded` (oder `failed`), **Abfragen sind kostenlos und verbrauchen keine Punkte**. Das vollständige Antwortformat und die Abfrage der Historie finden Sie in der [Maestro Aufgabenabfrage API-Dokumentation](/de/guides/maestro/maestro_tasks). ## Abrechnung **Die Abrechnung erfolgt nach tatsächlichem Endprodukt, fehlgeschlagene Aufgaben werden nicht berechnet.** Die Abrechnung basiert auf der tatsächlich gelieferten Dauer des Endprodukts und der Anzahl der Sprachen, und die Abrechnungsdauer überschreitet nicht die angeforderte Dauer. Wenn eine Sprache letztendlich nicht produziert wird, wird auch keine zusätzliche Gebühr von +6 Punkten für diese Sprache erhoben. Die Einreichung der Aufgabe selbst wird nicht separat berechnet, die Abfrage über `/maestro/tasks` ist kostenlos. Die Punkte für ein einzelnes Endprodukt werden wie folgt berechnet: ``` Punkte = Dauer des Endprodukts in Sekunden × 0.60 × Szenenmultiplikator + 6 × max(Anzahl der Sprachen − 1, 0) ``` Maestro berechnet einheitlich **0.60 Punkte / tatsächliche Endprodukt-Sekunde**, unterstützt 5–300 Sekunden, maximal 4 Sprachen und 1080p / 30fps Ausgabe; alle Aktionen und Szenen sind verfügbar. Szenenmultiplikator: `drama` 1.35× / `avatar` 1.15× / andere 1×. | Beispiel | Punkte | | - | -: | | Lite 30 Sekunden | 6 | | Standard 30 Sekunden | 18 | | Standard 60 Sekunden | 36 | | Standard 120 Sekunden | 72 | | Pro 30 Sekunden | 36 | | Pro 300 Sekunden | 360 | | Jede zusätzliche tatsächlich gelieferte Sprache | +6 | | `/maestro/tasks` Abfrage | Kostenlos | ## Fehlerbehandlung Wenn beim Aufruf der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die Informationen zurück. Zum Beispiel: * `400 invalid_request`：Ungültige Anfrage, möglicherweise aufgrund eines fehlenden `prompt` oder ungültiger Parameter. * `401 invalid_token`：Unbefugt, ungültiges oder fehlendes Autorisierungstoken. * `403 forbidden`：Verboten, unzureichendes Guthaben oder Zugriff. * `429 too_many_requests`：Zu viele Anfragen, Sie haben das Rate-Limit überschritten. * `500 api_error`：Interner Serverfehler, etwas ist auf dem Server schiefgelaufen. ### Beispiel für eine Fehlerantwort ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "Abruf fehlgeschlagen" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Schlussfolgerung Durch dieses Dokument haben Sie gelernt, wie Sie die Maestro Video-Generierungs-API verwenden: Mit nur einem natürlichen Sprach-`Prompt` können Sie Skripte, Materialien, Sprachaufnahmen, Musik, Schnitt, Untertitel und die Renderung des Endprodukts automatisch abschließen und unterstützen die Angabe von Videoarten, Stilen, Tonlagen, mehrsprachigen Ausgaben sowie Iterationen auf bestehenden Videos. Wir hoffen, dass dieses Dokument Ihnen hilft, die API besser zu integrieren und zu nutzen. Bei Fragen wenden Sie sich bitte jederzeit an unser technisches Support-Team. ## Verwandte Schnittstellen * [Maestro Aufgabenabfrage API Integrationsanleitung](/de/guides/maestro/maestro_tasks): Verwenden Sie `POST /maestro/videos`, um den `task_id` den Status und die Ergebnisse der Aufgabe abzufragen oder eine Liste historischer Aufgaben abzurufen (Polling kostenlos). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.