> ## 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 API-integrationsanvisningar för uppgiftsfrågor

> Maestro AI Video Studio API guide - Ace Data Cloud

Huvudfunktionen för Maestro API för uppgiftsfrågor är att, via uppgifts-ID:t som returneras av [Maestro API för videogenerering](/sv/guides/maestro/maestro_videos) (`POST /maestro/videos`), fråga efter uppgiftens körstatus och slutresultat.

Detta dokument introducerar integrationsanvisningarna för Maestro API för uppgiftsfrågor i detalj. Eftersom videogenerering är en asynkron uppgift behöver du efter inskick använda detta gränssnitt för att regelbundet fråga efter förlopp och färdig video, **frågningar är kostnadsfria 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 i [Ace Data Cloud-konsolen](https://platform.acedata.cloud/console/applications) och spara den för senare användning.

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

Om du ännu inte har loggat in eller registrerat dig omdirigeras du automatiskt till inloggningssidan för att registrera dig och logga in, och återvänder automatiskt till den aktuella sidan när det är klart.

**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 gratis kvot för att prova utan kostnad; om kvoten är otillräcklig kan du fylla på det gemensamma saldot i [konsolen](https://platform.acedata.cloud/console/coin).

> 📘 Fullständig dokumentation: [Maestro API för uppgiftsfrågor →](https://platform.acedata.cloud/documents/maestro-tasks)

## Fråga efter en enskild uppgift

Information om hur du skapar en videouppgift finns i dokumentationen [Maestro API för videogenerering](/sv/guides/maestro/maestro_videos). Vi använder ett av dess returnerade uppgifts-ID:n som exempel: `f57e99c4f60f4373a15517742ce2357d`, för att visa hur du frågar efter dess status och resultat.

### Ställ in begärandehuvuden och begärandetext

**Request Headers** inkluderar:

* `accept`: anger att svar i JSON-format ska tas emot, ange `application/json` här.
* `authorization`: nyckeln för att anropa API:t, som kan väljas direkt från rullgardinsmenyn efter ansökan.
* `content-type`: formatet för begärandetexten, ange `application/json` här.

**Request Body** inkluderar:

| Fält | Typ | Obligatoriskt | Beskrivning |
| - | - | - | - |
| `id` | string | Obligatoriskt vid fråga efter en enskild uppgift | `task_id` som returneras av `POST /maestro/videos` |
| `action` | string | Nej | `retrieve` (standard, fråga efter en enskild uppgift); vid fråga efter historiklista är värdet alltid `retrieve_batch` |

### Kodexempel

Motsvarande CURL-kod är följande:

```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",
  "action": "retrieve"
}'
```

Motsvarande Python-kod är följande:

```python theme={null}
import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

### Svarsexempel

När begäran har lyckats returnerar API:t status och resultat för denna videouppgift. Ett exempel på svaret när uppgiften är slutförd visas nedan (varje språk motsvarar en `variant`):

```json theme={null}
{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}
```

Fälten i returresultatet beskrivs nedan:

* `id`: ID:t för denna videouppgift, används för att unikt identifiera denna videogenereringsuppgift.
* `status`: uppgiftsstatus, med värdena `pending → planning → producing → succeeded` (eller `failed`). Huruvida uppgiften är slutförd avgörs av detta översta `status`.
* `elapsed`: tid som uppgiften har tagit (sekunder).
* `progress`: förloppsobjekt på toppnivå, `percent` (0–100) sätts som reserv till 100 när uppgiften har lyckats; `stage` och `message` återspeglar AI-regissörens senaste förloppshändelse (därför kan `stage` efter lyckad körning fortfarande vara det sista körningssteget, såsom `producing`), och kan direkt användas för att visa förloppsindikatorn.
* `request`: begärandetexten när uppgiften startades.
* `response`: uppgiftens returinformation.
  * `success`: om uppgiften lyckades.
  * `data.variants`: varje språk motsvarar ett färdigt videoobjekt, inklusive `lang`, `aspect`, `title`, `output_url` (nedladdningsadress för färdig video) med mera.
  * `data.project`: resultatet för hela projektet, inklusive `tarball_url` (projektpaket) och `outputs` (alla länkar till färdiga videor).
  * `data.progress`: en array med förloppshändelser som läggs till per steg (append-only-logg), och kan användas för att visa detaljerat realtidsförlopp.
* `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 när uppgiften ännu inte har startat.
* `finished_at`: tidpunkt då uppgiften slutfördes, Unix-tidsstämpel (sekunder). Är null när uppgiften inte är slutförd.

## Fråga efter historiklista

Genom att skicka `action: retrieve_batch` kan du hämta den senast utförda uppgiften för den aktuellt inloggade utföraren (sorterad i fallande ordning efter skapandetid), och det kan användas för listsidan ”Mina videor”. Historiklistan är isolerad per inloggningsidentitet.

**Request Body** inkluderar:

| Fält | Typ | Obligatoriskt | Beskrivning |
| - | - | - | - |
| `action` | string | Ja | Fast värde `retrieve_batch` |
| `limit` | int | Nej | Antal returnerade poster, standard är 20; giltigt intervall är 1–100 |
| `created_at_max` | int | Nej | Returnerar endast uppgifter som skapats strikt före denna Unix-tidsstämpel (exklusive gränsvärdet, för paginering) |
| `created_at_min` | int | Nej | Returnerar endast uppgifter som skapats strikt efter denna Unix-tidsstämpel (exklusive gränsvärdet) |

### Kodexempel

Motsvarande CURL-kod är följande:

```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 '{
  "action": "retrieve_batch",
  "limit": 20
}'
```

### Svarsexempel

När begäran har lyckats returnerar API:t den aktuella användarens historiska uppgiftslista:

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}
```

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 fallande ordning efter skapandetid; formatet för varje element är detsamma 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` blir `succeeded` eller `failed`. Det översta `progress.percent` kan användas för att visa en förloppsindikator i realtid. **Polling av detta gränssnitt är kostnadsfri och förbrukar inga poäng.**

## Felhantering

Vid anrop av API:t returnerar API:t 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

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

## Slutsats

Genom detta dokument har du fått lära 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 hämta 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

* [Anslutningsinstruktioner för Maestro API för videogenerering](/sv/guides/maestro/maestro_videos): Använd en naturlig språkprompt för att automatiskt producera en färdig video med undertexter, `task_id` returneras efter inskickning och använd sedan detta gränssnitt för att polla resultatet.


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