Integração e Uso da API Suno Tasks

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

Processo de Solicitação

Para usar a API Suno Tasks, você precisa primeiro ir à página de solicitação Suno Audios Generation API para solicitar o serviço correspondente e, em seguida, copiar o ID da tarefa da API Suno Audios Generation, como mostrado na imagem:

Por fim, acesse a página da API Tasks Suno Tasks API para solicitar o serviço correspondente. Após acessar a página, clique no botão “Acquire”, como mostrado na imagem: Página de Solicitação

Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando você a se registrar e fazer login. Após o registro e login, você será redirecionado automaticamente de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo que você use a API gratuitamente.

Exemplo de Solicitação

A API Suno Tasks pode ser usada para consultar os resultados da API Suno Audios Generation e da API Suno Lyrics Generation. Para saber como usar a API Suno Audios Generation, consulte o documento Suno Audios Generation API. Para saber como usar a API Suno Lyrics Generation, consulte Suno Lyrics Generation API. Usaremos um exemplo de ID de tarefa retornado pelo serviço da API Suno Audios Generation. Suponha que temos um ID de tarefa: eae26f89-b64b-404d-a80c-761996660b1c, a seguir, demonstraremos como passar um ID de tarefa.

Exemplo de Tarefa

Configurando Cabeçalhos 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

Pode-se 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.xhuoapi.ai/v1/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

import requests

url = "https://api.xhuoapi.ai/v1/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)

Exemplo de Resposta

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

{
  "_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,
  "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
  "request": {
    "action": "generate",
    "prompt": "Uma canção para o Natal"
  },
  "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": "Desejos de Férias",
        "image_url": "https://cdn2.suno.ai/image_b8a4f691-4b14-4120-a7e1-a54a27a0e57e.jpeg",
        "lyric": "[Verso]\nA neve está caindo suave e branca\nAs luzes estão piscando tão brilhantes\nCrianças estão rindo cheias de alegria\nO tempo de Natal finalmente chegou\n[Verso 2]\nSinos estão tocando na noite\nA lareira está quente com luz\nCanções de Natal cantadas perto da árvore\nTodos juntos, concordamos\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Verso 3]\nPresentes estão embrulhados com carinho\nA magia está flutuando no ar\nBiscoitos assando no forno\nAmor de Natal a ser dado\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Ponte]\nEstrelas estão brilhando no céu\nAbrace seus entes queridos, não pergunte por quê\nCoração a coração, estamos todos unidos\nNesta noite estamos encantados",
        "audio_url": "https://cdn1.suno.ai/b8a4f691-4b14-4120-a7e1-a54a27a0e57e.mp3",
        "video_url": "https://cdn1.suno.ai/b8a4f691-4b14-4120-a7e1-a54a27a0e57e.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "Uma canção para o Natal",
        "style": "pop",
        "duration": 154.44
      },
      {
        "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
        "title": "Desejos de Férias",
        "image_url": "https://cdn2.suno.ai/image_1a3343b2-2c24-4584-a2a7-687e2f97f09e.jpeg",
        "lyric": "[Verso]\nA neve está caindo suave e branca\nAs luzes estão piscando tão brilhantes\nCrianças estão rindo cheias de alegria\nO tempo de Natal finalmente chegou\n[Verso 2]\nSinos estão tocando na noite\nA lareira está quente com luz\nCanções de Natal cantadas perto da árvore\nTodos juntos, concordamos\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Verso 3]\nPresentes estão embrulhados com carinho\nA magia está flutuando no ar\nBiscoitos assando no forno\nAmor de Natal a ser dado\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Ponte]\nEstrelas estão brilhando no céu\nAbrace seus entes queridos, não pergunte por quê\nCoração a coração, estamos todos unidos\nNesta noite estamos encantados",
        "audio_url": "https://cdn1.suno.ai/1a3343b2-2c24-4584-a2a7-687e2f97f09e.mp3",
        "video_url": "https://cdn1.suno.ai/1a3343b2-2c24-4584-a2a7-687e2f97f09e.mp4",
        "created_at": "2024-08-31T05:44:54.806Z",
        "model": "chirp-v3.5",
        "prompt": "Uma canção para o Natal",
        "style": "pop",
        "duration": 147.16
      }
    ]
  }
}

返回结果一共有多个字段，request 字段就是发起任务时的 request body，同时response 字段是任务完成后返回的response body。字段介绍如下。

id，生成此歌曲任务的 ID，用于唯一标识此次歌曲生成任务。
request，查询歌曲任务中的请求信息。
response，查询歌曲任务中的返回信息。

Operação de consulta em lote

Isso é para consultar os detalhes da tarefa de música para vários IDs de tarefa, ao contrário do acima, é necessário selecionar a ação como retrieve_batch Corpo da Solicitação inclui:

ids：Array de IDs de tarefa enviados.
action：Método de operação na tarefa.

Configurar como mostrado na imagem abaixo:

Exemplo de Código

Pode-se notar que, no lado direito da página, vários códigos de linguagem já foram gerados automaticamente, como mostrado na imagem abaixo:

Parte do exemplo de código é o seguinte:

Exemplo de Resposta

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

  "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,
      "credential_id": "66614a7e-e624-494e-87a3-387099b8cbb4",
      "request": {
        "action": "generate",
        "prompt": "Uma canção para o Natal"
      },
      "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": "Desejos de Férias",
            "image_url": "https://cdn2.suno.ai/image_b8a4f691-4b14-4120-a7e1-a54a27a0e57e.jpeg",
            "lyric": "[Verso]\nA neve está caindo suave e branca\nAs luzes estão piscando tão brilhantes\nAs crianças estão rindo cheias de alegria\nO tempo de Natal finalmente chegou\n[Verso 2]\nOs sinos estão tocando à noite\nA lareira está quente com luz\nCanções de Natal cantadas perto da árvore\nTodos juntos, concordamos\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Verso 3]\nOs presentes estão embrulhados com carinho\nA mágica flutua no ar\nBiscoitos assando no forno\nAmor de Natal a ser dado\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Ponte]\nEstrelas estão brilhando no céu\nAbrace seus entes queridos, não pergunte por quê\nCoração a coração, estamos todos unidos\nNesta noite estamos encantados",
            "audio_url": "https://cdn1.suno.ai/b8a4f691-4b14-4120-a7e1-a54a27a0e57e.mp3",
            "video_url": "https://cdn1.suno.ai/b8a4f691-4b14-4120-a7e1-a54a27a0e57e.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "Uma canção para o Natal",
            "style": "pop",
            "duration": 154.44
          }, {
            "id": "1a3343b2-2c24-4584-a2a7-687e2f97f09e",
            "title": "Desejos de Férias",
            "image_url": "https://cdn2.suno.ai/image_1a3343b2-2c24-4584-a2a7-687e2f97f09e.jpeg",
            "lyric": "[Verso]\nA neve está caindo suave e branca\nAs luzes estão piscando tão brilhantes\nAs crianças estão rindo cheias de alegria\nO tempo de Natal finalmente chegou\n[Verso 2]\nOs sinos estão tocando à noite\nA lareira está quente com luz\nCanções de Natal cantadas perto da árvore\nTodos juntos, concordamos\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Verso 3]\nOs presentes estão embrulhados com carinho\nA mágica flutua no ar\nBiscoitos assando no forno\nAmor de Natal a ser dado\n[Refrão]\nDesejos de férias se tornam realidade\nHora de compartilhar a alegria com você\nSorrisos e abraços para todos\nFeliz Natal, vamos nos divertir\n[Ponte]\nEstrelas estão brilhando no céu\nAbrace seus entes queridos, não pergunte por quê\nCoração a coração, estamos todos unidos\nNesta noite estamos encantados",
            "audio_url": "https://cdn1.suno.ai/1a3343b2-2c24-4584-a2a7-687e2f97f09e.mp3",
            "video_url": "https://cdn1.suno.ai/1a3343b2-2c24-4584-a2a7-687e2f97f09e.mp4",
            "created_at": "2024-08-31T05:44:54.806Z",
            "model": "chirp-v3.5",
            "prompt": "Uma canção para o Natal",
            "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,
      "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://cdn2.suno.ai/image_b4f498b2-e86f-4172-926a-39da9df84dd3.jpeg",
            "lyric": "[Verso]\nEu acordo toda manhã\nOlho pela janela\nA luz do sol brilha intensa\nComeço de um novo dia\n[Verso 2]\nOs pássaros cantam alegres\nEu danço no jardim\nFlores lindas me cercam\nCada momento aqui é meu\n[Refrão]\nLa la la la la la\nCante comigo\nNão pare\nLa la la la la la\nAproveite a vida\n[Verso 3]\nO mar é azul e vasto\nAs ondas quebram suavemente\nNós caminhamos nas praias\nIndependente do tempo\n[Ponte]\nAproveite cada hora\nOuça minhas canções\nSinta-se livre\nFeliz\nDance ao ritmo agora\n[Refrão]\nLa la la la la la\nCante comigo\nNão pare\nLa la la la la la\nAproveite a vida",
            "audio_url": "https://cdn1.suno.ai/b4f498b2-e86f-4172-926a-39da9df84dd3.mp3",
            "video_url": "https://cdn1.suno.ai/b4f498b2-e86f-4172-926a-39da9df84dd3.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://cdn2.suno.ai/image_8b44fdf1-3b88-47ac-a351-7c4b4de60549.jpeg",
            "lyric": "[Verso]\nEu acordo todas as manhãs\nOlho pela janela\nA luz do sol brilha intensa\nComeço de um novo dia\n[Verso 2]\nOs pássaros cantam alegres\nEu danço no jardim\nFlores lindas me cercam\nCada momento aqui é meu\n[Refrão]\nLa la la la la la\nCante comigo\nNão pare\nLa la la la la la\nAlegre-se aproveitando a vida\n[Verso 3]\nO mar azul e vasto\nOndas batem suavemente\nNós caminhamos nas praias\nIndependente do tempo\n[Ponte]\nAproveite cada hora\nOuça minhas canções\nSinta-se livre\nFeliz\nDance ao ritmo agora\n[Refrão]\nLa la la la la la\nCante comigo\nNão pare\nLa la la la la la\nAlegre-se aproveitando a vida",
            "audio_url": "https://cdn1.suno.ai/8b44fdf1-3b88-47ac-a351-7c4b4de60549.mp3",
            "video_url": "https://cdn1.suno.ai/8b44fdf1-3b88-47ac-a351-7c4b4de60549.mp4",
            "created_at": "2024-08-31T05:55:09.345Z",
            "model": "chirp-v3.5",
            "prompt": "la la la",
            "style": "pop",
            "duration": 177.36
          }
        ]
      }
    }
  ],
  "count": 2
}

CURL

curl -X POST 'https://api.xhuoapi.ai/v1/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

import requests

url = "https://api.xhuoapi.ai/v1/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)

Tratamento de Erros

Ao chamar a API, se encontrar um erro, a API retornará o respectivo código de erro e mensagem. Por exemplo:

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.

Exemplo de Resposta de Erro

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

Conclusão

Através deste documento, você já entendeu como usar a API Suno Tasks para consultar detalhes de tarefas de músicas individuais ou em lote. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, entre em contato com nossa equipe de suporte técnico.

Documentation Index

​Processo de Solicitação

​Exemplo de Solicitação

​Exemplo de Tarefa

​Configurando Cabeçalhos 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

​Python

​Tratamento de Erros

​Exemplo de Resposta de Erro

​Conclusão

Processo de Solicitação

Exemplo de Solicitação

Exemplo de Tarefa

Configurando Cabeçalhos 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

Python

Tratamento de Erros

Exemplo de Resposta de Erro

Conclusão