> ## 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 Generering API Integrationsbeskrivning

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro är ett **Agent-nativt** video produktionsgränssnitt: du beskriver det önskade videon med en naturlig språk `prompt` (valfritt kan du bifoga referensbilder / videor / ljud med `file_urls`), en huvudlös "AI-regissör" kommer automatiskt att slutföra ämnesval, skriva manus, generera bilder, röstinspelning, musik, sammansättning och rendering, och slutligen producera en färdig video med undertexter och ladda upp den till CDN.

Denna artikel kommer att detaljerat beskriva Maestro video generering API:s integrationsbeskrivning, för att hjälpa dig att snabbt integrera och fullt utnyttja API:ets kapabiliteter.

Detta är ett **asynkront uppgifts** gränssnitt: efter inlämning kommer det omedelbart att returnera `task_id`, och du kan sedan använda [Maestro uppgiftsfråge API](/sv/guides/maestro/maestro_tasks) (`POST /maestro/tasks`) för att pollera resultatet (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 video generering API, börja med att gå till [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) för att få din API-token, som du ska spara för framtida bruk.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Om du inte har loggat in eller registrerat dig, kommer du automatiskt att omdirigeras till inloggningssidan för att registrera dig och logga in, och efter att ha slutfört detta kommer du automatiskt att återvända till den aktuella sidan.

**En API-token är tillräcklig för att anropa alla tjänster på plattformen, du behöver inte ansöka separat för varje tjänst.** Första ansökan ger en gratis kvot, så att du kan prova gratis; när kvoten är slut kan du ladda på allmänna medel i [konsolen](https://platform.acedata.cloud/console/coin).

> 📘 Fullständig dokumentation: [Maestro Video Generering API →](https://platform.acedata.cloud/documents/maestro-videos)

## Grundläggande användning

`POST https://api.acedata.cloud/maestro/videos`

Den mest grundläggande användningen kräver bara att du skickar en naturlig språk `prompt`, AI-regissören kommer automatiskt att bestämma manus, bilder, röstinspelning och redigering. Här ska vi först förstå de begärda rubrikerna och begärningskroppen.

**Request Headers** inkluderar:

* `accept`: vilken typ av format du vill ta emot som svar, här fylls i som `application/json`, det vill säga JSON-format.
* `authorization`: nyckeln för att anropa API:et, efter ansökan kan du direkt välja från rullgardinsmenyn.
* `content-type`: formatet på begärningskroppen, här fylls i som `application/json`.

**Request Body** inkluderar huvudsakligen:

* `prompt`: beskriv videon du vill göra med naturligt språk (ämne, vad som ska visas, stil, publik).
* `langs`: utmatningsspråk array, som `["zh-cn", "en"]`, standard `["zh-cn"]`.
* `aspect`: bildförhållande, `9:16` (standard) / `16:9` / `1:1`.
* `duration`: mållängd (sekunder), standard 30.

Alla fält i begärningskroppen visas i tabellen nedan:

| Fält | Typ | Obligatoriskt | Beskrivning |
| - | - | - | - |
| `prompt` | string | Ja | Beskriv videon du vill göra med naturligt språk (ämne, vad som ska visas, stil, publik). Manus, bilder, röstinspelning och redigering bestäms av AI. |
| `action` | string | Nej | `generate` (standard, generera ny video) / `remix` / `edit` / `extend` (iterera på en befintlig video, kräver `ref_task_id`). |
| `ref_task_id` | string | Nej | Obligatoriskt när `action` är remix / edit / extend: historisk uppgift `task_id` som utgångspunkt. |
| `file_urls` | string\[] | Nej | Referensmedia (bilder / videor / ljud-URL), till exempel produktbilder, logotyper, eller materialklipp som ska ha undertexter. |
| `langs` | string\[] | Nej | Utmatningsspråk, som `["zh-cn", "en"]`, standard `["zh-cn"]`. Den första är huvudspråket; varje ytterligare språk återanvänder bilder, bara mer röstinspelning + rendering, **varje ytterligare +6 poäng**. |
| `aspect` | string | Nej | `9:16` (standard) / `16:9` / `1:1`, enhetlig utmatning 1080p/30fps. |
| `duration` | int | Nej | Mållängd (sekunder), standard 30, stöder **5–300 sekunder**. Debiteras baserat på den faktiska videolängden, men överstiger inte begärd längd. |
| `scenario` | string | Nej | Videotyp: `auto` / `narrated` / `captions` / `avatar` / `drama`. `captions` kräver källvideo, `avatar` kräver porträtt. |
| `style` | string | Nej | Visuell stil förinställning: `auto` (standard) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, accepterar också fri text som mjuk prompt. Är ortogonal till `scenario`, ändrar inte rutten. |
| `voice` | string | Nej | Berättarröst (språkuppkopplad, fungerar över språk): `auto` (standard) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`. |

Nedan visas ett konkret exempel. Anta att vi vill generera en tvåspråkig, vertikal, 20 sekunder lång populärvetenskaplig video, motsvarande CURL-koden är som följer:

```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
}'
```

Motsvarande Python-kod är som följer:

```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)
```

När du klickar på kör kan du se att du omedelbart får ett resultat, som följer:

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

Beskrivningen av fälten i returresultatet är som följer:

* `success`：Om uppdraget har skickats in framgångsrikt.
* `task_id`：ID för den aktuella videoproduktionsuppgiften, som används för att [Maestro uppgiftsfråge-API](/sv/guides/maestro/maestro_tasks) för att pollera resultatet.
* `trace_id`：Spårnings-ID för denna begäran, som kan ges till teknisk support för att lokalisera problem.

Eftersom videoproduktionen tar tid, returnerar API:et här **omedelbart `task_id`**, och väntar inte på att videorenderingen ska vara klar. Nästa steg är att använda `task_id` för att pollera resultatet, se avsnittet "Hämta resultat".

## Specificera videotyp och stil (scenario / style)

Om `scenario` inte anges, bedömer AI automatiskt (lika med `auto`); om du vill fästa videon till en viss typ, ange det uttryckligen. Till exempel, för att göra en **stående kortfilm**, kan följande innehåll specificeras:

* `scenario`：Videotyp, här anges som `drama` (karaktärer + dialog i en kortfilm).
* `style`：Visuell stil, här anges som `cinematic` (filmisk känsla).

Exempel på CURL-kod:

```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": "Två rumskamrater bråkar om en katt och blir vänner igen, tre akter med vändningar, slutet är varmt",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

Vanliga kombinationer:

* Berättande kortfilm: `scenario: "narrated"`, stöds av Lite / Standard / Pro.
* Automatisk textning: `scenario: "captions"`, kräver att `file_urls` används för att skicka källvideon, stöds av Lite / Standard / Pro.
* Digital person / röstuppläsning: `scenario: "avatar"`, kräver att `file_urls` används för att skicka ett porträtt, stöds av Standard / Pro.
* Kortfilm: `scenario: "drama"` (karaktärer + dialog), stöds endast av Pro.
* `style` är en visuell stilinställning (som `modern` / `neon` / `luxury`), ändrar inte typ, påverkar endast upplevelsen.
* `voice` används för att specificera berättarröstens ton (som `warm-female` / `deep-male`), oberoende av språk, fungerar över språk.

Resultatet returneras på samma sätt som "grundläggande användning", också omedelbart returnera `task_id`.

## Flerspråkig utdata

Genom att ange flera språk i `langs` kan du producera flerspråkiga versioner på en gång. Den första är huvudspråket, och varje ytterligare språk kommer att **återanvända samma uppsättning bilder**, bara extra röst + rendering, så **varje ytterligare språk kostar endast +6 poäng**. Exempel:

```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": "Introducera vår intelligenta kundtjänstprodukt, framhäv 3 kärnpunkter",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

När uppdraget är slutfört kommer varje språk att motsvara en `variant` i resultatet (se [Maestro uppgiftsfråge-API](/sv/guides/maestro/maestro_tasks)).

## Iterera på befintlig video (remix / edit / extend)

Genom att ange `action` och den senaste uppgiftens `ref_task_id`, kan du göra differensändringar på den ursprungliga projektbasen (som "ändra titeln på akt 2", "byta röst", "justera ljusstyrkan"). Små ändringar går snabbt, stora ändringar kommer att göras om:

```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": "Byt ut öppningstiteln mot en mer slagkraftig, gör den övergripande färgsättningen mörkare"
}'
```

* `remix`：Återskapa den ursprungliga videostrukturen (bevara temat, justera presentationen).
* `edit`：Gör finjusteringar på specifika delar (som att byta titel, byta röst, justera färg).
* `extend`：Utöka innehållet baserat på den ursprungliga videon.

Resultatet returneras också omedelbart med ett nytt `task_id`, som du kan använda för att pollera och få den itererade filmen.

## Hämta resultat

Eftersom videoproduktionen tar tid, returnerar detta API omedelbart `task_id` efter inlämning, du behöver använda det för att [Maestro uppgiftsfråge-API](/sv/guides/maestro/maestro_tasks) för att pollera resultatet:

```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"
}'
```

När uppdraget är slutfört kommer det att returnera information om filmen (varje språk motsvarar en `variant`). `status` kommer att genomgå `pending → planning → producing → succeeded` (eller `failed`), **polling är gratis och kostar inga poäng**. Den fullständiga svarformatet och historiklistan kan du se i [Maestro uppgiftsfråge-API:s integrationsdokumentation](/sv/guides/maestro/maestro_tasks).

## Avgifter

**Avgifter debiteras baserat på den faktiska filmen efter slutförande, misslyckade uppdrag debiteras inte.** Avgifterna baseras på den faktiska levererade filmens längd och antal språk, och den debiterade längden kommer inte att överstiga begärningens längd. Om ett språk inte produceras slutligen, kommer det inte att debiteras +6 för det språket. Inlämning av uppdrag debiteras inte separat, `/maestro/tasks` polling är gratis.

Poängen för en enskild film beräknas enligt följande formel:

```
Poäng = Filmlängd i sekunder × 0.60 × scenmultiplikator + 6 × max(antal språk − 1, 0)
```

Maestro debiterar enhetligt **0.60 poäng/aktuell filmsekund**, stöder 5–300 sekunder, högst 4 språk och 1080p / 30fps utdata; alla åtgärder och scener kan användas.

Scenmultiplikator: `drama` 1.35× / `avatar` 1.15× / andra 1×.

| Exempel | Poäng |
| - | -: |
| Lite 30 sekunder | 6 |
| Standard 30 sekunder | 18 |
| Standard 60 sekunder | 36 |
| Standard 120 sekunder | 72 |
| Pro 30 sekunder | 36 |
| Pro 300 sekunder | 360 |
| Varje ytterligare språk som levereras | +6 |
| `/maestro/tasks` polling | Gratis |

## Felhantering

Vid anrop av API:et, om ett fel uppstår, kommer API:et att returnera motsvarande felkod och information. Till exempel:

* `400 invalid_request`：Felaktig begäran, möjligtvis på grund av en saknad `prompt` eller ogiltiga parametrar.
* `401 invalid_token`：Obehörig, ogiltig eller saknad auktoriseringstoken.
* `403 forbidden`：Förbjuden, otillräcklig balans eller åtkomst.
* `429 too_many_requests`：För många begärningar, du har överskridit hastighetsgränsen.
* `500 api_error`：Intern serverfel, något gick fel på servern.

### Exempel på felrespons

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "hämtning misslyckades"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Slutsats

Genom detta dokument har du fått en förståelse för hur man använder Maestro video-generering API: med bara en naturlig språk `prompt` kan du automatiskt slutföra manus, material, röstöverföring, musik, redigering, undertexter och rendering av den färdiga filmen, och det stöder specificering av videotyp, stil, tonläge, flerspråkig utdata samt iteration på befintliga videor. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda API:et. Om du har några frågor, tveka inte att kontakta vårt tekniska supportteam.

## Relaterade gränssnitt

* [Maestro uppgiftsfråge API integrationsbeskrivning](/sv/guides/maestro/maestro_tasks): Använd `POST /maestro/videos` för att hämta `task_id` och fråga uppgiftsstatus och resultat, eller hämta en historik över uppgifter (polling gratis).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.