Integração e Uso da API Veo Tasks

A principal função da API Veo Tasks é consultar o status de execução de uma tarefa através do ID da tarefa gerado pela API Veo Videos Generation. Este documento irá detalhar as instruções de integração da API Veo Tasks, ajudando você a integrar facilmente e aproveitar ao máximo o poderoso recurso dessa API. Com a API Veo Tasks, você pode consultar facilmente o status de execução das tarefas da API Veo Videos Generation.

Processo de Solicitação

Para usar a API Veo Videos Generation, primeiro acesse o console Ace Data Cloud para obter seu Token de API, que deve ser guardado para uso futuro.

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e logar; após a conclusão, você será redirecionado de volta para a página atual. Um Token de API é suficiente para acessar todos os serviços da plataforma, não sendo necessário solicitar um para cada serviço individualmente. A primeira solicitação oferece um crédito gratuito para que você possa experimentar; quando o crédito acabar, você pode recarregar o saldo geral no console.

📘 Documentação Completa: Veo Videos Generation API →

Exemplo de Solicitação

A API Veo Tasks pode ser usada para consultar os resultados da API Veo Videos Generation. Para saber como usar a API Veo Videos Generation, consulte a documentação Veo Videos Generation API. Usaremos um exemplo de ID de tarefa retornado pelo serviço da API Veo Videos Generation. Suponha que temos um ID de tarefa: 1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed, a seguir, demonstraremos como passar um ID de tarefa.

Exemplo de Tarefa

Configurando Cabeçalhos de Solicitação e Corpo da Solicitação

Request Headers incluem:

accept: especifica que a resposta deve ser no formato JSON, preenchido como application/json.
authorization: a chave para chamar a API, que pode ser selecionada diretamente após a solicitação.

Request Body inclui:

id: o ID da tarefa enviada.
action: a forma de operação na tarefa.

Configuração conforme mostrado na imagem abaixo:

Exemplo de Código

Você pode notar que, no lado direito da página, já foram gerados automaticamente códigos em várias linguagens, como mostrado na imagem:

Alguns exemplos de código são os seguintes:

CURL

curl -X POST 'https://api.acedata.cloud/veo/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "action": "retrieve"
}'

Python

import requests

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

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

payload = {
    "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
    "action": "retrieve"
}

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

Exemplo de Resposta

Após uma solicitação bem-sucedida, a API retornará as informações detalhadas da tarefa de vídeo aqui. Por exemplo:

{
  "_id": "68834c16550a4144a5112589",
  "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46",
  "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2",
  "created_at": 1753435158.509,
  "started_at": 1753435158.569,
  "finished_at": 1753435250.969,
  "elapsed": 92.4,
  "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae",
  "request": {
    "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc",
    "action": "text2video",
    "model": "veo2-fast",
    "prompt": "Caneca de café de cerâmica branca sobre balcão de mármore brilhante com luz da janela da manhã. A câmera gira lentamente 360 graus ao redor da caneca, pausando brevemente na alça."
  },
  "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
  "type": "videos",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
    "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
    "data": [
      {
        "id": "2f43ceed37944b4d836e1a1899dad0a1",
        "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
        "created_at": "2025-07-25 17:19:20",
        "complete_at": "2025-07-25 17:21:45",
        "state": "succeeded"
      }
    ]
  }
}

O resultado retornado contém vários campos, o campo request é o corpo da solicitação ao iniciar a tarefa, enquanto o campo response é o corpo da resposta retornada após a conclusão da tarefa. A descrição dos campos é a seguinte.

id, o ID que gerou esta tarefa de vídeo, usado para identificar exclusivamente esta tarefa de geração de vídeo.
request, informações da solicitação na tarefa de vídeo.
response, informações da resposta na tarefa de vídeo.
created_at, data e hora de criação da tarefa, timestamp Unix (segundos, ponto flutuante).
started_at, data e hora em que a tarefa começou a ser executada, timestamp Unix (segundos, ponto flutuante).
finished_at, data e hora em que a tarefa foi concluída, timestamp Unix (segundos, ponto flutuante). Este campo não é retornado se a tarefa não estiver concluída.
elapsed, tempo gasto na execução da tarefa, em segundos (ponto flutuante, com 3 casas decimais). Este campo não é retornado se a tarefa não estiver concluída.

Operação de Consulta em Lote

Esta operação é para consultar detalhes de várias tarefas com IDs, diferentemente do anterior, onde a ação deve ser selecionada como retrieve_batch. Request Body inclui:

ids: array de IDs de tarefas enviadas.
action: a forma de operação na tarefa.

Configuração conforme mostrado na imagem abaixo:

Exemplo de Código

Você pode notar que, no lado direito da página, já foram gerados automaticamente códigos em várias linguagens, como mostrado na imagem:

Alguns exemplos de código são os seguintes:

Exemplo de Resposta

Após uma solicitação bem-sucedida, a API retornará as informações detalhadas de todas as tarefas de vídeo em lote. Por exemplo:

{
  "items": [
    {
      "_id": "68834c16550a4144a5112589",
      "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
      "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46",
      "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2",
      "created_at": 1753435158.509,
      "started_at": 1753435158.569,
      "finished_at": 1753435250.969,
      "elapsed": 92.4,
      "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae",
      "request": {
        "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc",
        "action": "text2video",
        "model": "veo2-fast",
        "prompt": "Caneca de café de cerâmica branca em uma bancada de mármore brilhante com luz da janela da manhã. A câmera gira lentamente 360 graus ao redor da caneca, pausando brevemente na alça."
      },
      "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
        "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
        "data": [
          {
            "id": "2f43ceed37944b4d836e1a1899dad0a1",
            "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
            "created_at": "2025-07-25 17:19:20",
            "complete_at": "2025-07-25 17:21:45",
            "state": "succeeded"
          }
        ]
      }
    },
    {
      "_id": "68834c16550a4144a5112589",
      "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
      "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46",
      "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2",
      "created_at": 1753435158.509,
      "started_at": 1753435158.569,
      "finished_at": 1753435250.969,
      "elapsed": 92.4,
      "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae",
      "request": {
        "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc",
        "action": "text2video",
        "model": "veo2-fast",
        "prompt": "Caneca de café de cerâmica branca em uma bancada de mármore brilhante com luz da janela da manhã. A câmera gira lentamente 360 graus ao redor da caneca, pausando brevemente na alça."
      },
      "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
        "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
        "data": [
          {
            "id": "2f43ceed37944b4d836e1a1899dad0a1",
            "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
            "created_at": "2025-07-25 17:19:20",
            "complete_at": "2025-07-25 17:21:45",
            "state": "succeeded"
          }
        ]
      }
    }
  ],
  "count": 2
}

返回结果一共有多个字段，其中items是包含了批量视频任务的具体详情信息，每个视频任务的具体信息与上文的字段一样，字段信息如下。

items，批量视频任务的所有具体详情信息。 Ele é um array, onde cada elemento do array tem o mesmo formato do resultado da consulta de uma única tarefa acima.
count，此处批量查询视频任务的个数。

CURL

curl -X POST 'https://api.acedata.cloud/veo/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed","1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"],
  "action": "retrieve_batch"
}'

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

400 token_mismatched：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
400 api_not_implemented：Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
401 invalid_token：Não autorizado, token de autorização inválido ou ausente.
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.

错误响应示例

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

结论

通过本文档，您已经了解了如何使用 Veo Tasks API 进行查询单个或批量视频任务的所有具体详情信息。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Proxy

Avançado

Coding

Integração e Uso da API Veo Tasks

Processo de Solicitação

Exemplo de Solicitação

Exemplo de Tarefa

Configurando Cabeçalhos de Solicitação e Corpo da Solicitação

Exemplo de Código

CURL

Python

Exemplo de Resposta

Operação de Consulta em Lote

Exemplo de Código

Exemplo de Resposta

CURL

错误处理

错误响应示例

结论

​Processo de Solicitação

​Exemplo de Solicitação

​Exemplo de Tarefa

​Configurando Cabeçalhos de Solicitação e Corpo da Solicitação

​Exemplo de Código

​CURL

​Python

​Exemplo de Resposta

​Operação de Consulta em Lote

​Exemplo de Código

​Exemplo de Resposta

​CURL

​错误处理

​错误响应示例

​结论

Processo de Solicitação

Exemplo de Solicitação

Exemplo de Tarefa

Configurando Cabeçalhos de Solicitação e Corpo da Solicitação

Exemplo de Código

CURL

Python

Exemplo de Resposta

Operação de Consulta em Lote

Exemplo de Código

Exemplo de Resposta

CURL

错误处理

错误响应示例

结论