Integración y uso de la API de Luma Tasks

Luma Video Generation API guide - Ace Data Cloud

La principal función de la API de Luma Tasks es consultar el estado de ejecución de una tarea mediante el ID de tarea generado por la API de Luma Videos Generation.

Este documento detallará las instrucciones de integración de la API de Luma Tasks, ayudándole a integrar y aprovechar al máximo las potentes funciones de esta API. A través de la API de Luma Tasks, puede consultar fácilmente el estado de ejecución de las tareas de la API de Luma Videos Generation.

​

Proceso de solicitud

Para utilizar la API de Luma Videos Generation, primero debe obtener su token de API en el panel de control de Ace Data Cloud y guardarlo para uso futuro.

Si aún no ha iniciado sesión o registrado, será redirigido automáticamente a la página de inicio de sesión que le invita a registrarse e iniciar sesión, y después volverá automáticamente a la página actual.

Un token de API es suficiente para acceder a todos los servicios de la plataforma, sin necesidad de solicitar uno por cada servicio. La primera solicitud le otorgará un crédito gratuito para que pueda probarlo; si se queda sin créditos, puede recargar el saldo general en el panel de control.

📘 Documentación completa: API de Luma Videos Generation →

​

Ejemplo de solicitud

La API de Luma Tasks se puede utilizar para consultar los resultados de la API de Luma Videos Generation. Para saber cómo utilizar la API de Luma Videos Generation, consulte la documentación API de Luma Videos Generation.

Tomaremos como ejemplo un ID de tarea devuelto por el servicio de Luma Videos Generation, y demostraremos cómo utilizar esta API. Supongamos que tenemos un ID de tarea: 50fc6182-fa86-4c7d-ac12-2fa27ec2f151, a continuación, demostraremos cómo pasar un ID de tarea.

​

Ejemplo de tarea

​

Configuración de encabezados de solicitud y cuerpo de solicitud

Request Headers incluye:

• accept: especifica que se aceptan respuestas en formato JSON, aquí se debe llenar como application/json.
• authorization: la clave para llamar a la API, que puede seleccionarse directamente después de la solicitud.

Request Body incluye:

• id: el ID de tarea cargado.
• action: el método de operación sobre la tarea.

Configurado como se muestra en la siguiente imagen:

​

Ejemplo de código

Se puede observar que en el lado derecho de la página se han generado automáticamente códigos en varios lenguajes, como se muestra en la imagen:

Algunos ejemplos de código son los siguientes:

​

CURL

curl -X POST 'https://api.acedata.cloud/luma/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
  "action": "retrieve"
}'

​

Python

import requests

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

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

payload = {
    "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
    "action": "retrieve"
}

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

​

Ejemplo de respuesta

Después de una solicitud exitosa, la API devolverá la información detallada de la tarea de video aquí. Por ejemplo:

{
  "_id": "66d297a3550a4144a5a5db42",
  "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
  "api_id": "94fc9028-5a9f-4875-aae4-38463bd30ac5",
  "application_id": "06484a45-9d04-498a-98a7-67086dee8166",
  "created_at": 1725077411.961,
  "credential_id": "e6a879e5-a7c0-4f7b-9d6f-f9a837421a50",
  "request": {
    "action": "generate",
    "prompt": "Astronautas se trasladan del espacio a un volcán"
  },
  "trace_id": "0b7c1c1a-045c-4145-a434-609cba88f0a9",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
    "video_id": "4b088fc8-2bbc-4706-80a6-a0fb118adc1a",
    "prompt": "Astronautas se trasladan del espacio a un volcán",
    "video_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.mp4",
    "video_height": 752,
    "video_width": 1360,
    "state": "completed",
    "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.jpg",
    "thumbnail_width": 1360,
    "thumbnail_height": 752
  },
  "finished_at": 1725077566.241
}

El resultado devuelto tiene varios campos, el campo request es el cuerpo de la solicitud al iniciar la tarea, mientras que el campo response es el cuerpo de respuesta devuelto después de completar la tarea, cuyos resultados son consistentes con la solicitud y respuesta de la API de Luma Videos Generation. La descripción de los campos es la siguiente.

• id, el ID de la tarea de video generada, utilizado para identificar de manera única esta tarea de generación de video.
• video_id, el identificador único del video en la tarea de video consultada, que se necesita pasar como parámetro en caso de que se requiera realizar operaciones de extensión sobre el video en el futuro.
• request, información de la solicitud en la tarea de video consultada.
• response, información de la respuesta en la tarea de video consultada.
• created_at, la hora de creación de la tarea, marca de tiempo Unix (segundos, flotante).
• started_at, la hora de inicio de ejecución de la tarea, marca de tiempo Unix (segundos, flotante).
• finished_at, la hora de finalización de la tarea, marca de tiempo Unix (segundos, flotante). Este campo no se devuelve si la tarea no se ha completado.
• elapsed, el tiempo de ejecución de la tarea, en segundos (flotante, con 3 decimales). Este campo no se devuelve si la tarea no se ha completado.

​

Operación de consulta por lotes

Esto es para consultar los detalles de las tareas de video para múltiples IDs de tarea, a diferencia de lo anterior, se debe seleccionar la acción como retrieve_batch.

Request Body incluye:

• ids: un array de IDs de tarea cargados.
• action: el método de operación sobre la tarea.

Configurado como se muestra en la siguiente imagen:

​

Ejemplo de código

Se puede observar que en el lado derecho de la página se han generado automáticamente códigos en varios lenguajes, como se muestra en la imagen:

Algunos ejemplos de código son los siguientes:

​

Ejemplo de respuesta

Después de una solicitud exitosa, la API devolverá la información detallada de todas las tareas de video en lote. Por ejemplo:

{
  "items": [
    {
      "_id": "66d297a3550a4144a5a5db42",
      "id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
      "api_id": "94fc9028-5a9f-4875-aae4-38463bd30ac5",
      "application_id": "06484a45-9d04-498a-98a7-67086dee8166",
      "created_at": 1725077411.961,
      "credential_id": "e6a879e5-a7c0-4f7b-9d6f-f9a837421a50",
      "request": {
        "action": "generate",
        "prompt": "Astronautas se trasladan del espacio al volcán"
      },
      "trace_id": "0b7c1c1a-045c-4145-a434-609cba88f0a9",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "50fc6182-fa86-4c7d-ac12-2fa27ec2f151",
        "video_id": "4b088fc8-2bbc-4706-80a6-a0fb118adc1a",
        "prompt": "Astronautas se trasladan del espacio al volcán",
        "video_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.mp4",
        "video_height": 752,
        "video_width": 1360,
        "state": "completado",
        "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/50fc6182-fa86-4c7d-ac12-2fa27ec2f151.jpg",
        "thumbnail_width": 1360,
        "thumbnail_height": 752
      },
      "finished_at": 1725077566.241
    },
    {
      "_id": "66d29ed3550a4144a5a6c089",
      "id": "76a05f61-68ad-4c1a-838f-a00cd08cf65b",
      "api_id": "94fc9028-5a9f-4875-aae4-38463bd30ac5",
      "application_id": "06484a45-9d04-498a-98a7-67086dee8166",
      "created_at": 1725079250.921,
      "credential_id": "e6a879e5-a7c0-4f7b-9d6f-f9a837421a50",
      "request": {
        "action": "generate",
        "prompt": "la la la"
      },
      "trace_id": "338f1616-741d-40b6-8d62-c025434024c6",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "76a05f61-68ad-4c1a-838f-a00cd08cf65b",
        "video_id": "5a638d6a-7481-4c5e-8843-36c9d1b5bcd5",
        "prompt": "la la la",
        "video_url": "https://platform.cdn.acedata.cloud/luma/76a05f61-68ad-4c1a-838f-a00cd08cf65b.mp4",
        "video_height": 752,
        "video_width": 1360,
        "state": "completado",
        "thumbnail_url": "https://platform.cdn.acedata.cloud/luma/76a05f61-68ad-4c1a-838f-a00cd08cf65b.jpg",
        "thumbnail_width": 1360,
        "thumbnail_height": 752
      },
      "finished_at": 1725079406.71
    }
  ],
  "count": 2
}

​

CURL

curl -X POST 'https://api.acedata.cloud/luma/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["50fc6182-fa86-4c7d-ac12-2fa27ec2f151","76a05f61-68ad-4c1a-838f-a00cd08cf65b"],
  "action": "retrieve_batch"
}'

​

Python

import requests

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

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

payload = {
    "ids": ["50fc6182-fa86-4c7d-ac12-2fa27ec2f151","76a05f61-68ad-4c1a-838f-a00cd08cf65b"],
    "action": "retrieve_batch"
}

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

​

Manejo de errores

Al llamar a la API, si se encuentra con un error, la API devolverá el código de error correspondiente y la información. Por ejemplo:

• 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
• 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
• 401 invalid_token: No autorizado, token de autorización inválido o faltante.
• 429 too_many_requests: Demasiadas solicitudes, ha superado el límite de tasa.
• 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "la recuperación falló"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Conclusión

A través de este documento, usted ha comprendido cómo utilizar la API de Luma Tasks para consultar detalles específicos de tareas de video individuales o por lotes. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.