Maestro API-integrationsanvisningar för uppgiftsfrågor

Huvudfunktionen för Maestro API för uppgiftsfrågor är att, via uppgifts-ID:t som returneras av Maestro API för videogenerering (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 och spara den för senare användning.

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.

📘 Fullständig dokumentation: Maestro API för uppgiftsfrågor →

Fråga efter en enskild uppgift

Information om hur du skapar en videouppgift finns i dokumentationen Maestro API för videogenerering. 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:

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:

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

{
  "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:

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:

{
  "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

{
  "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: 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.

Getting Started

AI Samtal

AI Bild

AI Video

AI Ljud

Web & Data

CAPTCHA

Identitet

Coding

Fler guider

Maestro API-integrationsanvisningar för uppgiftsfrågor

Ansökningsprocess

Fråga efter en enskild uppgift

Ställ in begärandehuvuden och begärandetext

Kodexempel

Svarsexempel

Fråga efter historiklista

Kodexempel

Svarsexempel

Rekommendationer för polling

Felhantering

Exempel på felsvar

Slutsats

Relaterade gränssnitt

​Ansökningsprocess

​Fråga efter en enskild uppgift

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

​Kodexempel

​Svarsexempel

​Fråga efter historiklista

​Kodexempel

​Svarsexempel

​Rekommendationer för polling

​Felhantering

​Exempel på felsvar

​Slutsats

​Relaterade gränssnitt

Ansökningsprocess

Fråga efter en enskild uppgift

Ställ in begärandehuvuden och begärandetext

Kodexempel

Svarsexempel

Fråga efter historiklista

Kodexempel

Svarsexempel

Rekommendationer för polling

Felhantering

Exempel på felsvar

Slutsats

Relaterade gränssnitt