Guia de Integração da API de Consulta de Tarefas MiniMax H3

Este artigo apresenta a integração e o uso da API de consulta de tarefas MiniMax H3. Esta interface é usada para consultar, listar em lote ou excluir tarefas assíncronas criadas pela API de geração de vídeo MiniMax H3.

Processo de solicitação

Para usar a API de consulta de tarefas MiniMax H3, 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á automaticamente redirecionado para a página de login, onde será convidado a se registrar e fazer login. Após a conclusão, você retornará automaticamente à página atual. Um único API Token pode chamar todos os serviços da plataforma, não sendo necessário solicitar um separadamente para cada serviço. A primeira solicitação concede uma cota gratuita para experimentação sem custo; quando a cota for insuficiente, você poderá recarregar o saldo universal no console.

📘 Documentação completa: API de Consulta de Tarefas MiniMax H3 →

Ao consultar uma tarefa, deve-se usar o mesmo Token que criou essa tarefa. Recomenda-se salvar o Token como uma variável de ambiente e não escrevê-lo no código-fonte nem enviá-lo ao repositório de versões:

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

Visão geral da interface

Base URL：https://api.acedata.cloud
Endpoint：POST /minimax/tasks
Método de autenticação：incluir authorization: Bearer {token} no HTTP Header
Cabeçalhos de solicitação：
- accept: application/json
- content-type: application/json
Consultar uma única tarefa：action=retrieve, informar id
Consultar tarefas em lote：action=retrieve_batch, permite filtrar por ID da tarefa, intervalo de tempo e condições de paginação
Excluir tarefa：action=delete, informar id
Informações de cobrança：a consulta de tarefas é gratuita e não gera cobrança duplicada

Após criar um vídeo, é necessário salvar o task_id. Recomenda-se consultar aproximadamente a cada 10 segundos, até que a tarefa entre em um estado terminal.

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Ações aplicáveis	Descrição
`action`	string	Não	Todas	`retrieve`, `retrieve_batch` ou `delete`; o padrão é `retrieve`
`id`	string	Obrigatório condicionalmente	`retrieve`, `delete`	ID de uma única tarefa
`ids`	string[]	Não	`retrieve_batch`	Retorna apenas os IDs de tarefa especificados; quando omitido, lista as tarefas segundo outras condições
`limit`	integer	Não	`retrieve_batch`	Número máximo de tarefas retornadas nesta solicitação
`offset`	integer	Não	`retrieve_batch`	Número de tarefas a ignorar na lista de resultados, usado para paginação
`created_at_min`	number	Não	`retrieve_batch`	Limite inferior do horário de criação, timestamp Unix em segundos
`created_at_max`	number	Não	`retrieve_batch`	Limite superior do horário de criação, timestamp Unix em segundos

Os usos das três ações são os seguintes:

`action`	Uso	Parâmetros necessários	Estrutura da resposta
`retrieve`	Consulta o status e o resultado de uma tarefa	`id`	`{ "task": {...} }`
`retrieve_batch`	Consulta tarefas em lote por ID da tarefa, horário e condições de paginação	`ids`, intervalo de tempo, `offset`, `limit` opcionais	`{ "items": [...], "total": number }`
`delete`	Cancela ou exclui o registro da tarefa conforme seu status atual	`id`	`{ "id": "...", "deleted": true }`

Consultar uma única tarefa

curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "f5977217-ed2c-40da-adbe-93d08235618f"
  }'

Abaixo está a resposta de uma tarefa real bem-sucedida:

{
  "task": {
    "id": "f5977217-ed2c-40da-adbe-93d08235618f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786184658,
    "updated_at": 1786184758,
    "content": {
      "url": "https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4"
    },
    "resolution": "768P",
    "duration": 4,
    "usage": {
      "total_seconds": 4,
      "input_seconds": 0,
      "output_seconds": 4,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}

Abrir o resultado de vídeo real desta tarefa

Status da tarefa

`status`	Significado	Tratamento pelo cliente
`queued`	Entrou na fila, aguardando execução	Continuar a consulta
`running`	Está sendo gerado	Continuar a consulta
`succeeded`	Geração bem-sucedida	Ler `task.content.url`, interromper a consulta
`failed`	Falha na geração	Ler `task.error`, interromper a consulta
`cancelled`	A tarefa foi cancelada	Interromper a consulta

succeeded, failed e cancelled são todos estados terminais. Não continue consultando após entrar em um estado terminal.

Campos de resposta de task

Campo	Tipo	Descrição
`id`	string	ID da tarefa
`model`	string	Modelo usado pela tarefa, atualmente `MiniMax-H3`
`status`	string	Status atual da tarefa
`error.code`	string	Código de erro de falha, retornado somente em caso de falha
`error.message`	string	Motivo da falha, retornado somente em caso de falha
`created_at`	integer	Horário de criação, timestamp Unix em segundos
`updated_at`	integer	Horário da atualização de status mais recente, timestamp Unix em segundos
`content.url`	string	Endereço do vídeo após o sucesso
`resolution`	string	Resolução de saída, `768P` ou `2K`
`duration`	integer	Duração do vídeo de saída, em segundos
`usage.total_seconds`	integer	Quantidade total faturável, igual à soma dos segundos de vídeo de entrada e de saída
`usage.input_seconds`	integer	Quantidade faturável gerada pela entrada de vídeo de referência
`usage.output_seconds`	integer	Quantidade faturável gerada pelo vídeo de saída
`usage.input_image_count`	integer	Número de imagens de entrada nas estatísticas de cobrança
`ratio`	string	Proporção real de largura e altura da saída; ao usar `adaptive`, prevalece o resultado aqui
`task_type`	string	Para tarefas de geração de vídeo, é `generation`
`modality`	string	Para tarefas de vídeo, é `video`

Exemplo completo de polling em Python

O código abaixo lê o Token a partir da variável de ambiente e consulta uma vez a cada 10 segundos após criar a tarefa:

import os
import time

import requests

BASE_URL = "https://api.acedata.cloud"
HEADERS = {
    "Authorization": f"Bearer {os.environ['ACEDATACLOUD_API_KEY']}",
    "Content-Type": "application/json",
}

create_response = requests.post(
    f"{BASE_URL}/minimax/videos",
    headers=HEADERS,
    json={
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": "清晨的海边，一艘白色帆船驶过平静海面，镜头缓慢横移",
            }
        ],
        "resolution": "768P",
        "duration": 4,
        "ratio": "16:9",
    },
    timeout=30,
)
create_response.raise_for_status()
task_id = create_response.json()["task_id"]

while True:
    time.sleep(10)
    query_response = requests.post(
        f"{BASE_URL}/minimax/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "id": task_id},
        timeout=30,
    )
    query_response.raise_for_status()
    task = query_response.json()["task"]
    print(f"task={task_id} status={task['status']}")

    if task["status"] == "succeeded":
        print(f"video_url={task['content']['url']}")
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error") or task["status"])

Em ambientes de produção, deve-se definir um tempo limite total para o polling e usar recuo exponencial para 429 e 5xx temporários. Um tempo limite de rede não equivale a uma falha na geração; é possível continuar consultando com o mesmo task_id.

Consulta em lote

Especifique vários IDs de tarefa:

curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve_batch",
    "ids": ["TASK_ID_1", "TASK_ID_2"],
    "offset": 0,
    "limit": 20
  }'

Liste tarefas paginadas por intervalo de tempo:

{
  "action": "retrieve_batch",
  "created_at_min": 1786000000,
  "created_at_max": 1786200000,
  "offset": 0,
  "limit": 20
}

Os items na resposta em lote usam os mesmos campos de task da consulta de tarefa única, e total é o número total de tarefas correspondentes às condições de filtragem:

{
  "items": [
    {
      "id": "TASK_ID_1",
      "model": "MiniMax-H3",
      "status": "running",
      "resolution": "2K",
      "duration": 5,
      "ratio": "adaptive",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}

A janela de consulta de tarefas é dos últimos 7 dias. task_id além dessa janela pode retornar uma tarefa inválida; os sistemas de negócio devem salvar o ID ao criar uma tarefa e persistir a URL do resultado prontamente após o sucesso.

Cancelar ou excluir uma tarefa

curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "delete",
    "id": "YOUR_TASK_ID"
  }'

A ação depende do estado atual da tarefa:

Estado atual	Comportamento
`queued`	Cancela uma tarefa que ainda não foi iniciada
`succeeded`	Exclui o registro da tarefa
`failed`	Exclui o registro da tarefa
`running`	Não é permitido excluir ou cancelar, retorna um erro
`cancelled`	Não é permitido repetir a operação, retorna um erro

Exemplo de exclusão bem-sucedida:

{
  "id": "YOUR_TASK_ID",
  "deleted": true
}

Excluir o registro da tarefa não reverte cobranças já concluídas, nem pode garantir que cópias de vídeo já salvas sejam excluídas simultaneamente.

Respostas de falha e diagnóstico

Tarefas com falha ainda retornam o objeto task com HTTP 200, e o motivo é fornecido em task.error:

{
  "task": {
    "id": "YOUR_TASK_ID",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "task_type": "generation",
    "modality": "video"
  }
}

Quando a própria interface retorna 400, deve-se verificar action e os parâmetros de condição; 401 indica Token inválido, 429 indica consultas muito frequentes e 500 indica que o serviço está temporariamente indisponível. Tarefas com falha de geração não são cobradas; tarefas bem-sucedidas registram o uso de acordo com o usage final.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Guia de Integração da API de Consulta de Tarefas MiniMax H3

Processo de solicitação

Visão geral da interface

Parâmetros da solicitação

Consultar uma única tarefa

Status da tarefa

Campos de resposta de task

Exemplo completo de polling em Python

Consulta em lote

Cancelar ou excluir uma tarefa

Respostas de falha e diagnóstico

​Processo de solicitação

​Visão geral da interface

​Parâmetros da solicitação

​Consultar uma única tarefa

​Status da tarefa

​Campos de resposta de task

​Exemplo completo de polling em Python

​Consulta em lote

​Cancelar ou excluir uma tarefa

​Respostas de falha e diagnóstico

Processo de solicitação

Visão geral da interface

Parâmetros da solicitação

Consultar uma única tarefa

Status da tarefa

Campos de resposta de task

Exemplo completo de polling em Python

Consulta em lote

Cancelar ou excluir uma tarefa

Respostas de falha e diagnóstico