Conventions générales Suno et interrogation des tâches

curl --request GET \
  --url https://api.apimart.ai/v1/music/tasks/{task_id}

import requests

url = "https://api.apimart.ai/v1/music/tasks/{task_id}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.apimart.ai/v1/music/tasks/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apimart.ai/v1/music/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apimart.ai/v1/music/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.apimart.ai/v1/music/tasks/{task_id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apimart.ai/v1/music/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "task_id": "task_01ABC...",
  "status": "completed",
  "progress": 100,
  "data": {
    "result": {
      "music": [
        {
          "audio_id": "<track id, used with audio_index to locate it for subsequent operations>",
          "title": "Summer Breeze",
          "duration": 128.5,
          "lyrics": "……",
          "tags": "electronic, upbeat",
          "audio_url": "https://.../xxx.mp3",
          "image_url": "https://.../cover.png",
          "image_large_url": "https://.../cover_large.png",
          "video_url": "https://.../mv.mp4"
        }
      ]
    }
  }
}

{
  "task_id": "task_01ABC...",
  "status": "failed",
  "progress": 100,
  "data": {
    "error": {
      "message": "generation failed"
    }
  }
}

GET

music

tasks

{task_id}

Conventions générales Suno et interrogation des tâches

curl --request GET \
  --url https://api.apimart.ai/v1/music/tasks/{task_id}

import requests

url = "https://api.apimart.ai/v1/music/tasks/{task_id}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.apimart.ai/v1/music/tasks/{task_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apimart.ai/v1/music/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apimart.ai/v1/music/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.apimart.ai/v1/music/tasks/{task_id}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apimart.ai/v1/music/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "task_id": "task_01ABC...",
  "status": "completed",
  "progress": 100,
  "data": {
    "result": {
      "music": [
        {
          "audio_id": "<track id, used with audio_index to locate it for subsequent operations>",
          "title": "Summer Breeze",
          "duration": 128.5,
          "lyrics": "……",
          "tags": "electronic, upbeat",
          "audio_url": "https://.../xxx.mp3",
          "image_url": "https://.../cover.png",
          "image_large_url": "https://.../cover_large.png",
          "video_url": "https://.../mv.mp4"
        }
      ]
    }
  }
}

{
  "task_id": "task_01ABC...",
  "status": "failed",
  "progress": 100,
  "data": {
    "error": {
      "message": "generation failed"
    }
  }
}

Cette page décrit les conventions communes à toutes les API musicales Suno, à utiliser conjointement avec la documentation propre à chaque endpoint. Toutes les API de génération / édition sont des tâches asynchrones : soumettez pour obtenir un task_id, puis interrogez l’API décrite ici pour récupérer le résultat.

Authentification

Toutes les requêtes doivent inclure dans leurs en-têtes :

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Rendez-vous sur la page de gestion des clés API pour obtenir votre clé API.

Cycle de vie des tâches (toutes les API sont asynchrones)

Soumettre

POST /v1/music/generations/<opération> → renvoie immédiatement notre task_id :

{ "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }

Interroger

GET /v1/music/tasks/:task_id jusqu’à ce que status soit completed ou failed. Pendant la génération, status vaut pending et progress passe de en file d’attente 10 → prêt 50 → terminé 100. Intervalle de sondage recommandé : 3–5 s ; la génération musicale prend généralement 30–120 s.

Récupérer le résultat

Une fois terminée, récupérez audio_url / image_url / video_url, etc. depuis data.result.music[].

Enchaînement des statuts de tâche : submitted → pending → completed / failed. En cas d’échec, data.error.message donne la raison et le quota préautorisé est automatiquement remboursé.

Version version

v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, ce qui influe sur la qualité audio et la facturation ; la valeur par défaut est utilisée si non fournie. La disponibilité et les valeurs par défaut varient selon l’endpoint — certains ne prennent en charge qu’un sous-ensemble, et d’autres n’ont aucune dimension de version ; reportez-vous à la documentation propre à chaque endpoint.

Référencer la piste source : task_id + audio_index

Les opérations basées sur un morceau existant (extension / reprise / séparation de pistes / ajout de voix / découpage…) ne nécessitent de mémoriser aucun id en amont, il suffit de passer :

task_id : notre task_id de la tâche ayant produit la piste source
audio_index : quel morceau dans le music[] du résultat de cette tâche (indexé à partir de 1, par défaut 1 ; une génération produit généralement 2 morceaux : 1 et 2)

Si la source ne peut pas être résolue (tâche non terminée / indice hors limites / task_id inexistant), un 400 est renvoyé au moment de la soumission.

Interroger une tâche : GET /v1/music/tasks/:task_id

task_id

string

requis

Notre task_id renvoyé par l’API de soumission.

Interrogez cette API jusqu’à ce que status soit completed ou failed. Une fois terminée, récupérez les produits depuis data.result.music[].

Response

task_id

string

Identifiant unique de la tâche

status

string

Statut de la tâche : submitted / pending / completed / failed

progress

integer

Progression : en file d’attente 10 → prêt 50 → terminé 100

data

object

Données du résultat

Afficher Propriétés

result

object

Présent lorsque status vaut completed

Afficher Propriétés de result

music

array

Liste des produits (une génération produit généralement 2 morceaux)

Afficher Propriétés de music[]

audio_id

string

id de la piste, utilisé pour localiser via audio_index lors des opérations ultérieures

title

string

Titre

duration

number

Durée (en secondes)

lyrics

string

Paroles

Aperçu

Série Texte

Série Image

Série Vidéo

Série Audio

Série Modération

Gestion des uploads

Gestion des tâches

Gestion du compte

Conventions générales Suno et interrogation des tâches

Authentification

Cycle de vie des tâches (toutes les API sont asynchrones)

Version version

Référencer la piste source : task_id + audio_index

Interroger une tâche : GET /v1/music/tasks/:task_id

Response

​Authentification

​Cycle de vie des tâches (toutes les API sont asynchrones)

​Version version

​Référencer la piste source : task_id + audio_index

​Interroger une tâche : GET /v1/music/tasks/:task_id

​Response

Authentification

Cycle de vie des tâches (toutes les API sont asynchrones)

Version version

Référencer la piste source : task_id + audio_index

Interroger une tâche : GET /v1/music/tasks/:task_id

Response