Guía de integración de la API de consulta de tareas MiniMax H3

Este artículo presenta la integración y el uso de la API de consulta de tareas MiniMax H3. Esta interfaz se utiliza para consultar, listar por lotes o eliminar tareas asíncronas creadas por la API de generación de video MiniMax H3.

Proceso de solicitud

Para utilizar la API de consulta de tareas MiniMax H3, primero obtenga su API Token en la Consola de Ace Data Cloud y consérvelo como respaldo.

Si aún no ha iniciado sesión o no se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; al completarlo, volverá automáticamente a la página actual. Un solo API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluye crédito gratuito, que permite una experiencia gratuita; cuando el crédito sea insuficiente, puede recargar saldo general en la consola.

📘 Documentación completa: API de consulta de tareas MiniMax H3 →

Al consultar una tarea, debe utilizar el mismo Token con el que se creó dicha tarea. Se recomienda guardar el Token como una variable de entorno, y no escribirlo en el código fuente ni enviarlo al repositorio de versiones:

export ACEDATACLOUD_API_KEY="YOUR_API_KEY"

Resumen de la interfaz

Base URL：https://api.acedata.cloud
Endpoint：POST /minimax/tasks
Método de autenticación：Incluir authorization: Bearer {token} en el HTTP Header
Encabezados de solicitud：
- accept: application/json
- content-type: application/json
Consultar una sola tarea：action=retrieve, pasar id
Consultar tareas por lotes：action=retrieve_batch, se puede filtrar por ID de tarea, intervalo de tiempo y condiciones de paginación
Eliminar tarea：action=delete, pasar id
Descripción de facturación：La consulta de tareas es gratuita y no generará cargos duplicados

Después de crear un video, debe guardar el task_id. Se recomienda consultar aproximadamente cada 10 segundos hasta que la tarea entre en un estado terminal.

Parámetros de solicitud

Parámetro	Tipo	Obligatorio condicionalmente	Acción aplicable	Descripción
`action`	string	No	Todas	`retrieve`, `retrieve_batch` o `delete`; el valor predeterminado es `retrieve`
`id`	string	Obligatorio condicionalmente	`retrieve`, `delete`	ID de una sola tarea
`ids`	string[]	No	`retrieve_batch`	Solo devuelve los ID de tareas especificados; si se omite, lista las tareas según otras condiciones
`limit`	integer	No	`retrieve_batch`	Cantidad máxima de tareas devueltas en esta ocasión
`offset`	integer	No	`retrieve_batch`	Cantidad de tareas omitidas de la lista de resultados, para paginación
`created_at_min`	number	No	`retrieve_batch`	Límite inferior de tiempo de creación, marca de tiempo Unix, en segundos
`created_at_max`	number	No	`retrieve_batch`	Límite superior de tiempo de creación, marca de tiempo Unix, en segundos

Los usos de las tres acciones son los siguientes:

`action`	Uso	Parámetros necesarios	Estructura de respuesta
`retrieve`	Consultar el estado y resultado de una tarea	`id`	`{ "task": {...} }`
`retrieve_batch`	Consultar por lotes según ID de tarea, tiempo y condiciones de paginación	`ids` opcional, intervalo de tiempo, `offset`, `limit`	`{ "items": [...], "total": number }`
`delete`	Cancelar o eliminar el registro de una tarea según su estado actual	`id`	`{ "id": "...", "deleted": true }`

Consultar una sola tarea

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

A continuación se muestra la respuesta de una tarea exitosa real:

{
  "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 el resultado de video real de esta tarea

Estado de la tarea

`status`	Significado	Procesamiento del cliente
`queued`	Ha entrado en la cola y espera ejecución	Continuar sondeando
`running`	Se está generando	Continuar sondeando
`succeeded`	Generación exitosa	Leer `task.content.url`, detener el sondeo
`failed`	Error de generación	Leer `task.error`, detener el sondeo
`cancelled`	La tarea ha sido cancelada	Detener el sondeo

succeeded, failed y cancelled son todos estados terminales. No continúe sondeando después de entrar en un estado terminal.

Campos de respuesta de task

Campo	Tipo	Descripción
`id`	string	ID de la tarea
`model`	string	El modelo utilizado por la tarea, actualmente `MiniMax-H3`
`status`	string	Estado actual de la tarea
`error.code`	string	Código de error de fallo, devuelto solo en caso de fallo
`error.message`	string	Motivo del fallo, devuelto solo en caso de fallo
`created_at`	integer	Hora de creación, marca de tiempo Unix, en segundos
`updated_at`	integer	Hora de la actualización de estado más reciente, marca de tiempo Unix, en segundos
`content.url`	string	Dirección del video después del éxito
`resolution`	string	Resolución de salida, `768P` o `2K`
`duration`	integer	Duración del video de salida, en segundos
`usage.total_seconds`	integer	Cantidad total facturada, igual a la suma de los segundos de video de entrada y los segundos de salida
`usage.input_seconds`	integer	Cantidad facturada generada por la entrada de video de referencia
`usage.output_seconds`	integer	Cantidad facturada generada por el video de salida
`usage.input_image_count`	integer	Cantidad de imágenes de entrada en las estadísticas de facturación
`ratio`	string	Relación de aspecto de salida real; al usar `adaptive`, prevalece el resultado de aquí
`task_type`	string	La tarea de generación de video es `generation`
`modality`	string	La tarea de video es `video`

Ejemplo completo de sondeo en Python

El siguiente código lee el Token desde una variable de entorno, crea una tarea y luego consulta una vez cada 10 segundos:

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"])

El entorno de producción debe establecer un tiempo de espera total para el sondeo y usar retroceso exponencial para 429 y 5xx temporales. Un tiempo de espera de red no equivale a un fallo de generación; se puede continuar consultando con el mismo task_id.

Consulta por lotes

Especifique múltiples ID de tarea:

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

Enumere las tareas por páginas según el intervalo de tiempo:

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

Los items en la respuesta por lotes usan los mismos campos de task que la consulta de una sola tarea, y total es el número total de tareas que coinciden con los criterios de filtrado:

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

La ventana de consulta de tareas corresponde a los últimos 7 días. Los task_id que excedan esta ventana pueden devolver una tarea no válida; el sistema de negocio debe guardar el ID al crear la tarea y persistir oportunamente la URL del resultado tras el éxito.

Cancelar o eliminar una tarea

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

La acción depende del estado actual de la tarea:

Estado actual	Comportamiento
`queued`	Cancela la tarea que aún no ha comenzado
`succeeded`	Elimina el registro de la tarea
`failed`	Elimina el registro de la tarea
`running`	No se permite eliminar ni cancelar; devuelve un error
`cancelled`	No se permite repetir la operación; devuelve un error

Ejemplo de eliminación exitosa:

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

Eliminar el registro de la tarea no revertirá la facturación ya completada, ni puede garantizar que las copias de vídeo ya guardadas se eliminen al mismo tiempo.

Respuestas de fallo y solución de problemas

Las tareas fallidas aún devuelven un objeto task con HTTP 200, e indican la causa en 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"
  }
}

Cuando la propia interfaz devuelve 400, se deben comprobar action y los parámetros de condición; 401 indica que el Token no es válido, 429 indica que las consultas son demasiado frecuentes y 500 indica que el servicio no está disponible temporalmente. Las tareas con fallo de generación no se facturan; las tareas exitosas registran el uso según el usage final.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Guía de integración de la API de consulta de tareas MiniMax H3

Proceso de solicitud

Resumen de la interfaz

Parámetros de solicitud

Consultar una sola tarea

Estado de la tarea

Campos de respuesta de task

Ejemplo completo de sondeo en Python

Consulta por lotes

Cancelar o eliminar una tarea

Respuestas de fallo y solución de problemas

​Proceso de solicitud

​Resumen de la interfaz

​Parámetros de solicitud

​Consultar una sola tarea

​Estado de la tarea

​Campos de respuesta de task

​Ejemplo completo de sondeo en Python

​Consulta por lotes

​Cancelar o eliminar una tarea

​Respuestas de fallo y solución de problemas

Proceso de solicitud

Resumen de la interfaz

Parámetros de solicitud

Consultar una sola tarea

Estado de la tarea

Campos de respuesta de task

Ejemplo completo de sondeo en Python

Consulta por lotes

Cancelar o eliminar una tarea

Respuestas de fallo y solución de problemas