> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Integración y uso de Suno Tasks API

> Suno Music Generation API guide - Ace Data Cloud

La función principal de Suno Tasks API es consultar el estado de ejecución de una tarea introduciendo el ID de tarea generado por Suno Audios Generation API o Suno Lyrics Generation API.

Este documento presentará en detalle las instrucciones de integración de Suno Tasks API, ayudándole a integrar fácilmente y aprovechar al máximo las potentes funciones de esta API. A través de Suno Tasks API, puede realizar fácilmente consultas sobre el estado de ejecución de las tareas de Suno Lyrics Generation API o Suno Audios Generation API.

## Proceso de solicitud

Para utilizar Suno Audios Generation API, primero obtenga su API Token en la [consola de Ace Data Cloud](https://platform.acedata.cloud/console/applications) y guárdelo como respaldo.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Si aún no ha iniciado sesión o se ha registrado, será redirigido automáticamente a la página de inicio de sesión para invitarle a registrarse e iniciar sesión; una vez completado, volverá automáticamente a la página actual.

**Un solo API Token puede llamar a todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio.** La primera solicitud incluye créditos gratuitos para una experiencia sin costo; cuando los créditos sean insuficientes, puede recargar saldo general en la [consola](https://platform.acedata.cloud/console/coin).

> 📘 Documentación completa: [Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios)

## Ejemplo de solicitud

Suno Tasks API puede utilizarse para consultar los resultados de los dos API, Suno Audios Generation API y Suno Lyrics Generation API. Para saber cómo utilizar Suno Audios Generation API, consulte la documentación [Suno Audios Generation API ](https://platform.acedata.cloud/documents/suno-audios-integration). Para saber cómo utilizar Suno Lyrics Generation API, consulte [Suno Lyrics Generation API ](https://platform.acedata.cloud/documents/suno-lyrics-generation-integration).

Tomamos como ejemplo un ID de tarea devuelto por el servicio Suno Audios Generation API para demostrar cómo utilizar esta API. Supongamos que tenemos un ID de tarea: eae26f89-b64b-404d-a80c-761996660b1c, a continuación se demuestra cómo mediante la introducción de un ID de tarea.

### Imagen de ejemplo de tarea

![](https://cdn.acedata.cloud/bc6754.png)

### Configurar encabezados y cuerpo de la solicitud

**Request Headers** incluye:

* `accept`: especifica que se reciban resultados de respuesta en formato JSON; aquí se completa como `application/json`.
* `authorization`: la clave para llamar a la API, después de solicitarla puede seleccionarse directamente en la lista desplegable.

**Request Body** incluye:

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

La configuración se muestra en la siguiente imagen:

![](https://cdn.acedata.cloud/uo7t6n.png)

### Ejemplo de código

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

![](https://cdn.acedata.cloud/p6vi9o.png)

Algunos ejemplos de código son los siguientes:

#### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "eae26f89-b64b-404d-a80c-761996660b1c",
  "action": "retrieve"
}'
```

#### Python

```python theme={null}
import requests

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

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

payload = {
    "id": "eae26f89-b64b-404d-a80c-761996660b1c",
    "action": "retrieve"
}

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

### Ejemplo de respuesta

Después de que la solicitud se realice correctamente, la API devolverá la información detallada de la tarea de canción aquí. Por ejemplo:

```json theme={null}
{
  "_id": "66d2add5550a4144a5a88dfe",
  "id": "eae26f89-b64b-404d-a80c-761996660b1c",
  "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
  "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
  "created_at": 1725083093.077,
  "started_at": 1725083093.137,
  "finished_at": 1725083131.537,
  "elapsed": 38.4,
  "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
  "request": {
    "action": "generate",
    "prompt": "A song for Christmas"
  },
  "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "eae26f89-b64b-404d-a80c-761996660b1c",
    "data": [
      {
        "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e",
        "title": "Holiday Wishes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "A song for Christmas",
        "style": "pop",
        "duration": 154.44
      },
      {
        "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
        "title": "Holiday Wishes",
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
        "lyric": "[Verse]\nSnow is falling soft and white\nLights are twinkling oh so bright\nKids are laughing full of cheer\nChristmas time is finally here\n[Verse 2]\nBells are ringing in the night\nFireplace is warm with light\nCarols sung by the tree\nEveryone's together we agree\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Verse 3]\nGifts are wrapped with loving care\nMagic's floating in the air\nCookies baking in the oven\nChristmas love to be given\n[Chorus]\nHoliday wishes come true\nTime to share the joy with you\nSmiles and hugs for everyone\nMerry Christmas let's have fun\n[Bridge]\nStars are shining in the sky\nHold your loved ones don't ask why\nHeart to heart we're all united\nOn this night we are delighted",
        "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "A song for Christmas",
        "style": "pop",
        "duration": 147.16
      }
    ]
  }
}
```

El resultado devuelto tiene varios campos en total; el campo `request` es el request body al iniciar la tarea, mientras que el campo `response` es el response body devuelto tras completar la tarea. La descripción de los campos es la siguiente.

* `id`, el ID de la tarea de generación de esta canción, utilizado para identificar de forma única esta tarea de generación de canciones.
* `request`, la información de la solicitud en la consulta de la tarea de canción.
* `response`, la información de respuesta en la consulta de la tarea de canción.
* `created_at`, hora de creación de la tarea, marca de tiempo Unix (segundos, punto flotante).
* `started_at`, hora de inicio de ejecución de la tarea, marca de tiempo Unix (segundos, punto flotante).
* `finished_at`, hora de finalización de la tarea, marca de tiempo Unix (segundos, punto flotante). Este campo no se devuelve cuando la tarea no está finalizada.
* `elapsed`, tiempo de ejecución de la tarea, en segundos (punto flotante, conservando 3 decimales). Este campo no se devuelve cuando la tarea no está finalizada.

## Operación de consulta por lotes

Esto es para consultar los detalles de las tareas de canciones mediante múltiples ID de tarea. A diferencia de lo anterior, es necesario seleccionar la acción como retrieve\_batch.

**Request Body** incluye:

* `ids`: la matriz de ID de tarea cargados.
* `action`: la forma de operar sobre la tarea.

Configúrelo como se muestra en la siguiente imagen:

![](https://cdn.acedata.cloud/dqeknz.png)

### Ejemplo de código

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

![](https://cdn.acedata.cloud/1yk792.png)

Algunos ejemplos de código son los siguientes:

### Ejemplo de respuesta

Una vez que la solicitud se haya realizado correctamente, la API devolverá la información detallada específica de todas las tareas de canciones por lotes de esta vez. Por ejemplo:

```json { theme={null}
  "items": [
    {
      "_id": "66d2add5550a4144a5a88dfe",
      "id": "eae26f89-b64b-404d-a80c-761996660b1c",
      "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
      "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
      "created_at": 1725083093.077,
      "started_at": 1725083093.137,
      "finished_at": 1725083131.537,
      "elapsed": 38.4,
      "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
      "request": {
        "action": "generate",
        "prompt": "A song for Christmas"
      },
      "trace_id": "e13d385a-077e-4376-be01-3465b61ca0fd",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "eae26f89-b64b-404d-a80c-761996660b1c",
        "data":
[
          {
            "id": "b8a4f691-4b14-4120-a7e1-a54a27a0e57e",
            "title": "Deseos navideños",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verso]\nLa nieve cae suave y blanca\nLas luces brillan tan intensamente\nLos niños ríen llenos de alegría\nLa Navidad finalmente está aquí\n[Verso 2]\nLas campanas suenan en la noche\nLa chimenea está cálida con luz\nVillancicos cantados junto al árbol\nTodos estamos juntos, estamos de acuerdo\n[Coro]\nLos deseos navideños se hacen realidad\nEs hora de compartir la alegría contigo\nSonrisas y abrazos para todos\nFeliz Navidad, divirtámonos\n[Verso 3]\nLos regalos están envueltos con amoroso cuidado\nLa magia flota en el aire\nGalletas horneándose en el horno\nAmor navideño para ser dado\n[Coro]\nLos deseos navideños se hacen realidad\nEs hora de compartir la alegría contigo\nSonrisas y abrazos para todos\nFeliz Navidad, divirtámonos\n[Puente]\nLas estrellas brillan en el cielo\nAbraza a tus seres queridos, no preguntes por qué\nDe corazón a corazón todos estamos unidos\nEn esta noche estamos encantados",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "Una canción para Navidad",
            "style": "pop",
            "duration": 154.44
          }, {
            "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
            "title": "Deseos navideños",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verso]\nLa nieve cae suave y blanca\nLas luces brillan tan intensamente\nLos niños ríen llenos de alegría\nLa Navidad finalmente está aquí\n[Verso 2]\nLas campanas suenan en la noche\nLa chimenea está cálida con luz\nVillancicos cantados junto al árbol\nTodos estamos juntos, estamos de acuerdo\n[Coro]\nLos deseos navideños se hacen realidad\nEs hora de compartir la alegría contigo\nSonrisas y abrazos para todos\nFeliz Navidad, divirtámonos\n[Verso 3]\nLos regalos están envueltos con amoroso cuidado\nLa magia flota en el aire\nGalletas horneándose en el horno\nAmor navideño para ser dado\n[Coro]\nLos deseos navideños se hacen realidad\nEs hora de compartir la alegría contigo\nSonrisas y abrazos para todos\nFeliz Navidad, divirtámonos\n[Puente]\nLas estrellas brillan en el cielo\nAbraza a tus seres queridos, no preguntes por qué\nDe corazón a corazón todos estamos unidos\nEn esta noche estamos encantados",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "Una canción para Navidad",
            "style": "pop",
            "duration": 147.16
          }
        ]
      }
    }, {
      "_id": "66d2b03c550a4144a5a8d93d",
      "id": "0d3ed03b-912b-4f7d-941b-8441323cb77b",
      "api_id": "09a26295-5972-4392-9318-dcd9b218f90d",
      "application_id": "ab46a066-ad82-4180-b66b-49dedf8e8a2f",
      "created_at": 1725083708.53,
      "started_at": 1725083708.59,
      "finished_at": 1725083746.99,
      "elapsed": 38.4,
      "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
      "request": {
        "action": "generate",
        "prompt": "la la la"
      },
      "trace_id": "29ebb919-1126-4156-86cc-4ad899432a8c",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "0d3ed03b-912b-4f7d-941b-8441323cb77b",
        "data": [
          {
            "id": "b4f498b2-e86f-4172-926a-39da9df84dd3",
            "title": "La La La",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verso]\nMe despierto cada mañana\nMiro a través de la ventana\nLa luz del sol brilla intensamente\nEl comienzo de un nuevo día\n[Verso 2]\nLos pájaros cantan alegremente\nBailo en el jardín\nHermosas flores me rodean\nCada momento aquí es mío\n[Coro]\nLa la la la la la\nCanta conmigo\nNo te detengas\nLa la la la la la\nAlégrate disfrutando de la vida\n[Verso 3]\nEl mar azul y vasto\nLas olas rompen suavemente\nCaminamos por las playas\nIndependientemente del tiempo\n[Puente]\nAprovecha cada hora\nEscucha mis canciones\nSiéntete libre\nFeliz\nBaila al ritmo ahora\n[Coro]\nLa la la la la la\nCanta conmigo\nNo te detengas\nLa la la la la la\nAlégrate disfrutando de la vida",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:55:09.345Z",
            "model": "chirp-v3.5",
            "prompt": "la la la",
            "style": "pop",
            "duration": 154.32
          },
{
            "id": "8b44fdf1-3b88-47ac-a351-7c4b4de60549",
            "title": "La La La",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verso]\nMe despierto cada mañana\nMiro por la ventana\nLuz del sol brillando intensamente\nComienzo de un nuevo día\n[Verso 2]\nLos pájaros cantan alegremente\nBailo en el jardín\nMe rodean flores hermosas\nCada momento aquí es mío\n[Estribillo]\nLa la la la la la\nCanta conmigo\nNo pares\nLa la la la la la\nAlégrate disfrutando de la vida\n[Verso 3]\nEl mar azul y vasto\nLas olas fluyen dulcemente\nCaminamos por las playas\nIndependientemente del tiempo\n[Puente]\nAtrapa cada hora\nEscucha mis cantos\nSiéntete libre\nFeliz\nBaila al ritmo ahora\n[Estribillo]\nLa la la la la la\nCanta conmigo\nNo pares\nLa la la la la la\nAlégrate disfrutando de la vida",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
            "created_at": "2024-08-31T05:55:09.345Z",
            "model": "chirp-v3.5",
            "prompt": "la la la",
            "style": "pop",
            "duration": 177.36
          }
        ]
      }
    }
  ],
  "count": 2
}
```

El resultado devuelto tiene varios campos en total, entre los cuales `items` contiene la información detallada específica de las tareas de canciones por lotes; la información específica de cada tarea de canción es la misma que los campos anteriores, y la información de los campos es la siguiente.

* `items`, toda la información detallada específica de las tareas de canciones por lotes. Es un arreglo, y el formato de cada elemento del arreglo es el mismo que el resultado devuelto de la consulta de una sola tarea anterior.
* `count`, el número de tareas de canciones consultadas por lotes aquí.

#### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"],
  "action": "retrieve_batch"
}'
```

#### Python

```python theme={null}
import requests

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

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

payload = {
    "ids": ["eae26f89-b64b-404d-a80c-761996660b1c","0d3ed03b-912b-4f7d-941b-8441323cb77b"],
    "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 un error, la API devolverá el código de error y la información correspondientes. Por ejemplo:

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

### Ejemplo de respuesta de error

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

## Conclusión

A través de este documento, ya ha comprendido cómo usar la API de Suno Tasks para consultar toda la información detallada específica de tareas de canciones individuales o por lotes. Esperamos que este documento pueda ayudarle a integrar y usar mejor esta API. Si tiene alguna pregunta, no dude en contactar con nuestro equipo de soporte técnico.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.