API de consultation et d'historique des morceaux

Mis à jour le 2026-09-18 · équipe Suno-API

Cette page couvre trois points d'accès de consultation gratuits :

Si vous avez utilisé le mode reçu d'acceptation (accept_mode=async) sur un point d'accès de génération, ce que vous détenez est un numéro de reçu, pas un ID de morceau. Suivez la progression avec GET /api/music/requests/{request_id} et revenez aux points d'accès de cette page une fois le vrai song_id obtenu. Voir « Mode reçu d'acceptation » dans l'API de génération en mode simple.

Authentification et périmètre des données

Les trois points d'accès s'authentifient avec la même clé d'API :

Authorization: Bearer YOUR_API_KEY

L'historique des morceaux est isolé par le user_id auquel appartient la clé d'API. Plusieurs clés créées sous le même compte principal peuvent lire l'historique de ce compte, mais pas celui d'un autre utilisateur ni d'un autre compte de sous-site.

Les points d'accès d'historique ne renvoient que de vrais morceaux générés. Sont exclus :

• les enregistrements de réservation de génération commençant par pending: ;
• les téléversements d'audio source et les enregistrements de téléversement amélioré ;
• les sous-résultats, comme la séparation voix/accompagnement et les stems ;
• les morceaux d'autres utilisateurs ou de comptes de sous-site.

1. Consulter l'état de génération

Consulte l'état actuel et le résultat final d'un ou de plusieurs ID de morceau.

Point d'accès : POST /api/music/query

Facturation : Gratuit.

Headers

Paramètres du body

Exemple de requête

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Exemple de réponse

[
  {
    "song_id": "clip_id_1",
    "song_title": "Titre du morceau",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Texte des paroles",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Notes de compatibilité

L'ancienne documentation peut présenter song_ids sous forme de tableau. Aujourd'hui, une chaîne séparée par des virgules est recommandée, ce qui correspond à l'appel réel du point d'accès.

song_ids doit contenir de vrais ID de morceaux. Un ID de réservation commençant par pending: n'est pas un song_id final et ne peut pas être utilisé ici ; consulter uniquement des ID de réservation peut renvoyer un tableau vide [].

Le model, le model_version ou le model_name de plateforme d'une réponse peuvent conserver des valeurs historiques. Les nouvelles tâches doivent utiliser suno-v6, suno-v6-wild ou suno-v6-mini ; de suno-v2 à suno-v5-5 sont retirés, et voir ces noms dans l'historique ne signifie pas que le modèle accepte encore des envois.

Tant qu'une tâche est pending, submitted ou processing, audio_url, video_url et cover_url peuvent être vides : c'est normal pour une tâche inachevée. Ne concluez pas à un échec sur la seule base d'une adresse vide ; fiez-vous au status et interrogez de nouveau une fois l'état terminé. Ce n'est que si l'état est terminé et que les adresses restent vides qu'il convient de contacter le support en indiquant le song_id.

⚠️ Les adresses audio vivent 7 jours — transférez vos fichiers à temps

L'audio_url, le video_url (et d'autres adresses de médias comme le WAV) renvoyés ici sont servis depuis le stockage objet de la plateforme et expirent par défaut au bout de 7 jours : les fichiers sont recyclés et l'ancienne adresse renvoie alors 404.

• Déplacez les fichiers vers votre propre stockage dans ces 7 jours ; ne considérez pas l'adresse comme un lien pérenne.
• Une adresse expirée n'oblige pas à régénérer le morceau et n'est pas facturée à nouveau : rappelez ce point d'accès (POST /api/music/query) pour obtenir une nouvelle adresse valide de ce morceau.

2. Consulter l'historique des morceaux du compte

Liste les morceaux générés par le compte principal auquel appartient la clé d'API courante. Utile pour construire votre propre liste de morceaux, un sélecteur ou une page d'historique.

Point d'accès : GET /api/music/songs

Facturation : Gratuit.

Paramètres de query

Les résultats sont triés par created_at puis par ID d'enregistrement interne, en ordre décroissant, ce qui garde une pagination stable.

Retrouver un envoi ayant expiré : les points d'accès de génération ne donnent aucune réponse intermédiaire avant l'acceptation. Si votre client a expiré ou si la connexion s'est coupée à l'envoi, la commande peut déjà être acceptée et en cours de génération. Jetez un œil à ce point d'accès (les plus récents d'abord) : les morceaux acceptés apparaissent normalement dans la liste. Ne renvoyez qu'après avoir confirmé son absence réelle, pour éviter de payer deux fois. Voir « Temps d'attente et réglage du timeout » dans la Présentation de la nouvelle API.

Exemple de requête

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "La ville dans la nuit",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Champs de la réponse

Le point d'accès de liste ne renvoie ni prompts, ni champs de facturation, ni informations de compte, ni réponses brutes. Pour les prompts et les paramètres de génération, appelez le point d'accès de détail du morceau.

3. Consulter les paramètres de génération

Consulte le prompt, le style, le modèle et le morceau source que la plateforme a conservés lors de la génération.

Point d'accès : GET /api/music/songs/:song_id

Facturation : Gratuit.

Seuls les morceaux du compte principal auquel appartient la clé d'API courante peuvent être lus. Les morceaux d'autres utilisateurs ou de comptes de sous-site sont uniformément traités comme « morceau introuvable ».

Paramètre de chemin

Exemple de requête

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "La ville dans la nuit",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "rues de ville après la pluie, paroles sur des retrouvailles",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "La ville dans la nuit",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

Les champs de parameters

Le champ prompt_view (voir le prompt, ajouté le 2026-09-28)

prompt_view est une structure normalisée dédiée à « voir le prompt » : elle organise les données en sections fixes par type de génération, si bien que le client n'a plus à décider quel champ afficher. C'est un champ purement additif — les anciens champs (parameters, parameter_retention) gardent leur nom et leur sens, et les clients qui n'analysent pas le nouveau champ ne sont pas affectés du tout.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Mode personnalisé",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Quatre heures du matin#701f37", "title_base": "Quatre heures du matin", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "électro guochao, sub bass profond, synthé rétro",
    "style_tags": "électro guochao, sub bass profond, synthé rétro",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

Champs pouvant apparaître dans extended : vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode, plus le groupe des effets sonores sound_type / sound_bpm / sound_key / sound_loop. Les valeurs vides ne sont jamais renvoyées.

Trois règles d'affichage (appliquez-les au lieu de déduire) :

1. Distinguez l'origine du style : avec style_source=suno_derived, affichez « style (déduit par Suno à partir de votre description) » et jamais « votre style » ;
2. Les prompts internes n'apparaissent jamais : les types de reprise avec voix ne renvoient que les 【exigences de style】/【exigences de reprise】 saisies par l'utilisateur ; la structure fixe que nous assemblons pour le modèle n'apparaît dans aucun champ (les données historiques sont nettoyées de la même façon) ;
3. Ne devinez pas les paramètres absents : si extended ne le contient pas, il n'a pas été enregistré à l'époque — utilisez retention pour expliquer pourquoi.

Notes sur la conservation des paramètres

parameter_retention sert à distinguer « une valeur vide a été transmise explicitement » de « ce champ n'a jamais été stocké historiquement » :

• core_parameters_available : si l'enregistrement principal de la tâche existe ; normalement true pour un détail valide ;
• extended_parameters_available : si un enregistrement de tâche musicale étendue associé a été trouvé ;
• sources : de quelles tables de données provient cette réponse ;
• unavailable_fields : champs qui ne peuvent pas être restaurés de façon fiable depuis l'historique ; ils renvoient null dans parameters.

Les morceaux historiques ordinaires conservent généralement le prompt, le style, le titre actuel, le modèle, le type de génération et le morceau source, mais n'ont pas stocké séparément tous les paramètres avancés. La plateforme ne devine jamais les valeurs manquantes à partir du generation_type.

Certaines tâches musicales étendues ont aussi conservé le prompt original, le style, le titre, le modèle, ainsi que custom_mode, negative_tags, vocal_gender, style_weight et weirdness_constraint. Même lorsqu'un enregistrement étendu existe, instrumental, lyrics_mode et wait_audio peuvent rester irrécupérables.

Les titres peuvent être renommés par l'utilisateur par la suite. Quand une tâche historique ordinaire n'a pas conservé de titre original distinct, parameters.title peut être le titre actuel ; quand un enregistrement de tâche étendue existe, le titre de génération d'origine qui y est stocké est privilégié.

Introuvable ou sans autorisation

Les erreurs métier utilisent une enveloppe de réponse uniforme. Quand le morceau n'existe pas ou n'appartient pas au compte courant :

{
  "success": false,
  "message": "song not found"
}

Cette erreur métier renvoie actuellement HTTP 200 ; jugez donc le résultat sur le champ success. Une clé d'API absente, invalide, expirée ou désactivée renvoie HTTP 401.

Notes de sécurité

Les points d'accès d'historique et de détail ne renvoient jamais :

• de clés d'API ni d'ID de jeton ;
• de champs de quota, de facturation ou de remboursement ;
• d'informations de compte ni de réponses brutes ;
• de clés internes du stockage objet ;
• d'erreurs d'administrateur ni d'erreurs de ressources internes.