Saltar para o conteúdo principal
A principal função da API de consulta de tarefas 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 Maestro (POST /maestro/videos). Este documento apresentará em detalhes a documentação de integração da API de consulta de tarefas Maestro. Como a geração de vídeos é uma tarefa assíncrona, após o envio é necessário usar esta interface 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 Maestro, primeiro acesse o Console do Ace Data Cloud para obter seu API Token e guarde-o para uso posterior. Se você ainda não estiver conectado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login; após a conclusão, retornará automaticamente à página atual. Um único API Token pode chamar todos os serviços da plataforma, sem necessidade de solicitar um separadamente para cada serviço. A primeira solicitação concede uma cota gratuita para experimentação; quando a cota for insuficiente, é possível recarregar o saldo geral no console.
📘 Documentação completa: API de consulta de tarefas Maestro →

Consultar uma única tarefa

Sobre como criar uma tarefa de vídeo, consulte a documentação da API de geração de vídeos Maestro. 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 o resultado da resposta a ser recebido no formato JSON, preenchido aqui como 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, preenchido aqui como application/json.
O Request Body inclui:

Exemplo de código

O código CURL correspondente é o seguinte:
O código Python correspondente é o seguinte:

Exemplo de resposta

Após a solicitação ser bem-sucedida, a API retornará o status e o resultado desta tarefa de vídeo. Um exemplo de retorno quando a tarefa for concluída é o seguinte (o array variants contém um vídeo final):
Os campos do resultado retornado são descritos a seguir:
  • id: o ID desta tarefa de vídeo, usado para identificar exclusivamente esta tarefa de geração de vídeo.
  • status: status da tarefa, com valor pending → planning → producing → succeeded (ou failed). A conclusão da tarefa deve ser determinada por este status de nível superior.
  • elapsed: tempo decorrido da tarefa (segundos).
  • progress: objeto de progresso de nível superior. percent (0–100) será 100 após a conclusão bem-sucedida da tarefa; stage e message refletem o evento de progresso mais recente do diretor de IA (portanto, após a conclusão, stage ainda poderá ser a última etapa de execução, como producing) e podem ser usados diretamente para exibir uma barra de progresso.
  • request: corpo da solicitação ao iniciar a tarefa.
  • response: informações retornadas pela tarefa.
    • success: indica se a tarefa foi bem-sucedida.
    • data.variants: contém um objeto de vídeo final no idioma selecionado, incluindo lang, aspect, title, output_url (URL para download do vídeo final) etc.
    • data.project: artefatos de todo o projeto, incluindo tarball_url (pacote do projeto) e outputs (link do vídeo final).
    • data.progress: array de eventos de progresso adicionados por etapa (log somente de anexação), que pode ser usado para exibir o progresso detalhado em tempo real.
  • created_at: horário de criação da tarefa, carimbo de data/hora Unix (segundos).
  • started_at: horário de início da execução da tarefa, carimbo de data/hora Unix (segundos). Será null se a tarefa ainda não tiver começado.
  • finished_at: hora de conclusão da tarefa, carimbo de data/hora Unix (segundos). É null quando a tarefa não foi concluída.

Consultar lista de histórico

Basta passar action: retrieve_batch para obter as tarefas recentes do executor atualmente conectado (em ordem decrescente de hora 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:

Exemplo de código

O código CURL correspondente é o seguinte:

Exemplo de resposta

Após a solicitação ser bem-sucedida, a API retornará a lista de tarefas históricas do usuário atual:
A introdução aos 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 filtradas 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 de «consultar uma única tarefa».

Recomendações de polling

Como a produção de vídeo leva mais 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. Você pode usar 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, caso ocorra um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:
  • 401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
  • 404 not_found: Tarefa não encontrada, o task_id fornecido não existe.
  • 429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
  • 500 api_error: Erro interno do servidor, algo deu errado no servidor.

Exemplo de resposta de erro

Conclusão

Por meio deste documento, você já entendeu como usar a API de consulta de tarefas do Maestro para consultar o status e os resultados 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 usar melhor esta API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico a qualquer momento.

Interfaces relacionadas