> ## 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.

# Documentação de integração da API de consulta de tarefas do Maestro

> Maestro AI Video Studio API guide - Ace Data Cloud

A principal função da API de consulta de tarefas do Maestro é consultar o status de execução e o resultado final de uma tarefa por meio do ID da tarefa retornado pela [API de geração de vídeos do Maestro](/pt/guides/maestro/maestro_videos) (`POST /maestro/videos`).

Este documento apresentará detalhadamente a documentação de integração da API de consulta de tarefas do Maestro. Como a geração de vídeos é uma tarefa assíncrona, após o envio é necessário usar esta API para consultar o progresso e o vídeo final por polling; **o polling é gratuito e não consome créditos.**

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

## Processo de solicitação

Para usar a API de consulta de tarefas do Maestro, primeiro acesse o [Console do Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu API Token e guarde-o para uso posterior.

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

Se você ainda não tiver feito login ou se registrado, será redirecionado automaticamente para a página de login para se registrar e fazer login, retornando automaticamente à página atual após a conclusão.

**Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar um para cada serviço separadamente.** A primeira solicitação concede uma cota gratuita para experimentação; quando a cota for insuficiente, é possível recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentação completa: [API de consulta de tarefas do Maestro →](https://platform.acedata.cloud/documents/maestro-tasks)

## Consultar uma única tarefa

Para saber como criar uma tarefa de vídeo, consulte a documentação da [API de geração de vídeos do Maestro](/pt/guides/maestro/maestro_videos). Usaremos como exemplo um ID de tarefa retornado por ela: `f57e99c4f60f4373a15517742ce2357d`, para demonstrar como consultar seu status e resultado.

### Configurar os cabeçalhos e o corpo da solicitação

Os **Request Headers** incluem:

* `accept`: especifica que o resultado da resposta deve ser recebido no formato JSON; preencha aqui com `application/json`.
* `authorization`: a chave para chamar a API, que pode ser selecionada diretamente na lista suspensa após a solicitação.
* `content-type`: o formato do corpo da solicitação; preencha aqui com `application/json`.

O **Request Body** inclui:

| Campo | Tipo | Obrigatório ao consultar uma única tarefa | Descrição |
| - | - | - | - |
| `id` | string | Sim | O `task_id` retornado por `POST /maestro/videos` |
| `action` | string | Não | `retrieve` (padrão, consulta uma única tarefa); ao consultar a lista de histórico, é fixo como `retrieve_batch` |

### Exemplo de código

O código CURL correspondente é o seguinte:

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

O código Python correspondente é o seguinte:

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

### Exemplo de resposta

Após a solicitação ser bem-sucedida, a API retornará o status e o resultado desta tarefa de vídeo. O exemplo de retorno quando a tarefa é concluída é o seguinte (cada idioma corresponde a um `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
        }
      ]
    }
  }
}
```

A introdução aos campos do resultado retornado é a seguinte:

* `id`: o ID desta tarefa de vídeo, usado para identificar exclusivamente esta tarefa de geração de vídeo.
* `status`: o status da tarefa, com valores `pending → planning → producing → succeeded` (ou `failed`). Para saber se a tarefa foi concluída, prevalece este `status` de nível superior.
* `elapsed`: tempo decorrido da tarefa (segundos).
* `progress`: objeto de progresso de nível superior; `percent` (0–100) será garantido como 100 após o sucesso da tarefa; `stage` e `message` refletem o evento de progresso mais recente do diretor de IA (portanto, após o sucesso, `stage` ainda pode ser a última etapa de execução, como `producing`), podendo ser usado diretamente para exibir uma barra de progresso.
* `request`: o corpo da solicitação ao iniciar a tarefa.
* `response`: as informações de retorno da tarefa.
  * `success`: se a tarefa foi bem-sucedida.
  * `data.variants`: cada idioma corresponde a um objeto de vídeo final, incluindo `lang`, `aspect`, `title`, `output_url` (endereço para download do vídeo final) e outros.
  * `data.project`: o produto de todo o projeto, incluindo `tarball_url` (pacote do projeto) e `outputs` (todos os links dos vídeos finais).
  * `data.progress`: um array de eventos de progresso adicionados por etapa (log somente de adição), que pode ser usado para exibir o progresso detalhado em tempo real.
* `created_at`: horário de criação da tarefa, timestamp Unix (segundos).
* `started_at`: horário de início da execução da tarefa, timestamp Unix (segundos). É null quando a tarefa ainda não começou.
* `finished_at`: horário de conclusão da tarefa, timestamp Unix (segundos). É null quando a tarefa não foi concluída.

## Consultar a lista de histórico

Passe `action: retrieve_batch` para obter as tarefas mais recentes do executor atualmente autenticado (em ordem decrescente de horário de criação), podendo ser usado na página de lista «Meus vídeos». A lista de histórico é isolada por identidade de login.

O **Request Body** inclui:

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `action` | string | Sim | Fixo como `retrieve_batch` |
| `limit` | int | Não | Número de itens retornados, padrão 20; o intervalo válido é 1–100 |
| `created_at_max` | int | Não | Retorna apenas tarefas estritamente anteriores a este timestamp Unix (sem incluir o valor de limite, para paginação) |
| `created_at_min` | int | Não | Retorna apenas tarefas estritamente posteriores a este timestamp Unix (sem incluir o valor de limite) |

### Exemplo de código

O código CURL correspondente é o seguinte:

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

### Exemplo de resposta

Após a solicitação ser bem-sucedida, a API retornará a lista de tarefas históricas do usuário atual:

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

A introdução dos campos do resultado retornado é a seguinte:

* `count`：O número total de tarefas visíveis para o executor atualmente autenticado, não afetado pelas condições de tempo ou por `limit`.
* `items`：O array de tarefas filtrado pelas condições de tempo e por `limit`, ordenado por tempo de criação em ordem decrescente; o formato de cada elemento é consistente com o resultado retornado por «Consultar uma única tarefa».

## Recomendações de polling

Como a produção de vídeo leva bastante tempo, o `status` passará por `pending → planning → producing → succeeded` (ou `failed`). Recomenda-se realizar polling a cada 5–10 segundos, até que o `status` se torne `succeeded` ou `failed`. É possível usar o `progress.percent` de nível superior para exibir uma barra de progresso em tempo real. **O polling desta interface é gratuito e não consome créditos.**

## Tratamento de erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:

* `401 invalid_token`：Unauthorized, invalid or missing authorization token.
* `404 not_found`：Task not found, the given task\_id does not exist.
* `429 too_many_requests`：Too many requests, you have exceeded the rate limit.
* `500 api_error`：Internal server error, something went wrong on the server.

### Exemplo de resposta de erro

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

## Conclusão

Por meio deste documento, você já aprendeu como usar a API de consulta de tarefas do Maestro para consultar o status e o resultado de uma única tarefa, bem como obter a lista de tarefas históricas do usuário atual. Esperamos que este documento possa ajudá-lo a integrar e utilizar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento.

## Interfaces relacionadas

* [Instruções de integração da API de geração de vídeo Maestro](/pt/guides/maestro/maestro_videos)：Use uma instrução em linguagem natural para produzir automaticamente um vídeo finalizado com legendas; após o envio, será retornado um `task_id`, e então use esta interface para consultar o resultado por polling.


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