Passer au contenu principal
POST https://api.acedata.cloud/suno/projects est l’interface Beta de gestion des projets multipistes. Distinguez la création, la sauvegarde, la génération de candidats, la soumission de candidats et l’exportation via action.
À l’exception de retrieve, chaque opération nécessite Idempotency-Key. La même clé et la même requête relisent uniquement le résultat d’origine ; la même clé avec une requête différente renvoie 409. Lorsqu’une génération payante rencontre un délai d’expiration réseau ou que le résultat de soumission est incertain, interrogez d’abord avec l’ID de tâche d’origine ou la même clé d’idempotence, et ne renvoyez pas directement avec une autre clé.

Identifiants et unités de temps

start_seconds / end_seconds sont les secondes dans l’audio source ; start_beats / end_beats sont les temps sur la ligne temporelle du projet. state.timing.bps est le nombre de temps par seconde, avec une valeur par défaut de 2. Par exemple, un segment de 41 secondes commençant au temps 0 se termine par défaut au temps 82. L’intervalle en secondes de generate_track sert à spécifier la référence de génération et ne garantit pas que le candidat ait uniquement la durée de cet intervalle.

Flux d’opérations

Si vous effectuez uniquement un remplacement local, un audio source utilisable existant suffit et il n’est pas nécessaire d’effectuer d’abord render ; si l’audio source est déjà dans le projet, vous pouvez également ignorer upload et add_track. render_audio_id est uniquement la référence obligatoire de generate_track. Lors de la soumission d’une opération asynchrone, { "task_id": "...", "trace_id": "..." } est d’abord renvoyé, ce qui ne signifie pas que la génération a réussi. Interrogation :
Une tâche est considérée comme réussie uniquement lorsqu’elle possède finished_at et que son response.success vaut true ; lorsque response.success=false, lisez response.error. Bien que save puisse contenir task_id, il se termine de manière synchrone dans cette interface. upload, render, generate_track et replace_section ne modifient pas la version du projet ; après la réussite de save, add_track, commit_candidate et remove_track, vous devez récupérer le nouveau version_id.

Conventions de requête

Les exemples suivants présentent de manière enchaînée la transmission des ID et des versions entre les opérations. Les réponses ne listent que les champs liés à l’étape actuelle ; lors de l’intégration, remplacez les ID d’exemple par les valeurs de réponse de l’application actuelle.

Création et lecture d’un projet

Créer un projet : create

Requête :
Réponse :

Lire un projet : retrieve

Requête :```json { “action”: “retrieve”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6” }
{ “success”: true, “trace_id”: “a335ceac-5cb7-4b1c-9773-77b9d5c84bd7”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “title”: “Suno Projects Documentation Verification 2026-10-09”, “state”: { “tracks”: [], “timing”: { “bps”: 2 } } } }
{ “action”: “save”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “title”: “Suno Projects Documentation Verification 2026-10-09”, “state”: { “tracks”: [], “timing”: { “bps”: 2 } } }
{ “success”: true, “task_id”: “ab172b47-4d89-404b-a10e-71f67c36ccba”, “trace_id”: “fc7b2e43-7a7a-4276-8671-27008a1153ea”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “state”: { “timing”: { “bps”: 2 }, “tracks”: [] } } }
{ “action”: “upload”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “audio_url”: “https://cdn.acedata.cloud/suno_demo.mp3”, “async”: true }
{ “task_id”: “3fe60d9c-cada-4aab-b1f4-8c0b28247243”, “trace_id”: “4a54cb56-befb-45da-8001-2a20cdb67d18” }
{ “success”: true, “task_id”: “3fe60d9c-cada-4aab-b1f4-8c0b28247243”, “trace_id”: “4a54cb56-befb-45da-8001-2a20cdb67d18”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “candidate”: { “audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “title”: “suno_demo”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/b21be571-bfe4-47c1-b59c-2abc55c6f9c3.m4a” } } }
{ “action”: “add_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “8f0c62fb-304f-420e-9707-426e8b64b5e3”, “audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “name”: “Source demo”, “start_beats”: 0 }
{ “task_id”: “03f0f74f-c3ed-4d03-896b-74b2a366838b”, “trace_id”: “3442a5b2-7b16-4225-b8af-24eb872d0e07” }
{ “success”: true, “task_id”: “03f0f74f-c3ed-4d03-896b-74b2a366838b”, “trace_id”: “3442a5b2-7b16-4225-b8af-24eb872d0e07”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cf8a6aa5-0f6d-4da3-844e-cc156aa1b731”, “track”: { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9”, “name”: “Source demo”, “clips”: [ { “clipId”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “startBeats”: 0, “endBeats”: 82 } ] } } }
{ “id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “type”: “audio”, “name”: “Generated piano”, “clips”: [], “takeLanes”: [], “mute”: false, “solo”: false, “amplitude”: 1, “instrument”: { “type”: “song” }, “color”: “#7251F7” }
{ “success”: true, “task_id”: “783f8d49-cc59-4a65-9f9d-ca00e7d7b8a9”, “trace_id”: “0a9c8f13-7e4f-4915-8a40-010ce4ac61dc”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d” } }
{ “action”: “render”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “title”: “Suno Projects Docs Source Mix”, “lyrics”: “[Instrumental]”, “async”: true }
{ “task_id”: “adc559fa-4a87-4a53-9336-28d4302a151b”, “trace_id”: “165fde93-f34b-4b0b-a7cd-0fba7d7ac154” }
{ “success”: true, “task_id”: “adc559fa-4a87-4a53-9336-28d4302a151b”, “trace_id”: “165fde93-f34b-4b0b-a7cd-0fba7d7ac154”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “render_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “audio_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/41038732-4dc4-40bf-b00d-2728d99bc26e.m4a” } }
{ “action”: “generate_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “source_audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “render_audio_id”: “41038732-4dc4-40bf-b00d-2728d99bc26e”, “model”: “chirp-v5”, “start_seconds”: 12, “end_seconds”: 20, “stem_control_tags”: “add Piano”, “title”: “Documentation Piano Take”, “tags”: “gentle piano, instrumental”, “async”: true }
{ “task_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “trace_id”: “81a4cf70-d9f6-48b3-a889-b68e74d6307f” }
{ “success”: true, “task_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “trace_id”: “81a4cf70-d9f6-48b3-a889-b68e74d6307f”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “operation_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “candidates”: [ { “id”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “title”: “Documentation Piano Take”, “state”: “complete”, “duration”: 41.76, “audio_url”: “https://cdn.acedata2.cloud/suno/20f8ffe5063111b1eb866336242e2c0b2b9b7103a8dc0c0c19106cbf50843f86.mp3” }, { “id”: “18d6e0a4-2d73-43c3-92e9-be87cf11e139”, “title”: “Documentation Piano Take”, “state”: “complete”, “duration”: 40.96, “audio_url”: “https://cdn.acedata2.cloud/suno/c1c50a016333e3a037f18f651c0a88061880b3069aee7c6a258d6c9cdc041a6b.mp3” } ] } }
Les 12–20 secondes de la demande constituent l’intervalle de référence de l’audio source, l’audio candidat dure environ 41 secondes ; start_seconds/end_seconds ne garantissent pas la durée de sortie.

Adopter le candidat : commit_candidate

La génération ne produit que des candidats, elle ne les place pas automatiquement dans le projet. commit_candidate vérifie que le candidat appartient toujours à la version actuelle. Les candidats de remplacement partiel ne peuvent être soumis automatiquement que lorsque leur durée réelle peut correspondre de manière fiable à l’audio source complet ou à l’intervalle sélectionné ; en cas de non-correspondance, le projet d’origine est conservé et une erreur est renvoyée, il n’est pas possible de les raccorder de force en devinant manuellement les battements.
Réponse d’acceptation :
État terminal de la tâche :

Exporter après la soumission

Après avoir soumis le candidat de nouvelle piste, l’exportation de la chanson entière contenant ce candidat est refusée. Demande et état terminal :
Réponse d’acceptation :
État terminal de la tâche :
Le fait que le lien de l’audio candidat soit accessible ne signifie pas que le projet qui l’inclut puisse nécessairement être exporté. Lors de la réception de studio_audio_unavailable, le projet d’origine doit être conservé et la disponibilité de l’audio référencé doit être vérifiée.

Remplacer un clip existant

replace_section peut directement utiliser l’audio source existant, sans avoir besoin d’exporter d’abord un mixage. La génération ne renvoie que des candidats ; lors de la soumission, sélectionnez la piste d’origine qui contient le clip source unique.

Générer un candidat de remplacement : replace_section

Réponse d’acceptation :
État final de la tâche :

La durée des candidats ne correspond pas

Lors de la soumission de candidats de remplacement local, track_id doit pointer vers la piste originale contenant le segment source unique, et start_beats et end_beats doivent être omis. L’interface ne mettra à jour le projet que lorsque la durée du candidat peut correspondre de manière fiable à l’audio source complet ou à la plage sélectionnée. Après avoir sélectionné une plage de 8 secondes, les deux candidats font 36 secondes, ce qui ne correspond ni aux 41 secondes de l’audio original ni aux 8 secondes sélectionnées. La soumission de l’un des candidats renvoie :
Réponse d’acceptation :
État final de la tâche :
Par conséquent, la piste originale n’a pas été modifiée. En cas de cette erreur, les candidats doivent être conservés pour l’écoute et le traitement manuel ; ne les considérez pas comme ayant été intégrés avec succès au projet, et ne relancez pas automatiquement une génération payante.

Supprimer une piste

remove_track nécessite le version_id actuel et state.tracks[].id ; après succès, utilisez la nouvelle version renvoyée. Ci-dessous, suppression de la piste candidate qui ne peut pas être utilisée pour l’exportation de la chanson complète, puis relecture de l’état du projet.
Réponse :
Lire à nouveau le projet :

Exporter après suppression

Après avoir supprimé cette piste candidate, la piste source originale est toujours présente ; l’exportation réussit à nouveau en utilisant la dernière version :
Réponse d’acceptation :
État final de la tâche :
L’audio_url exportée avec succès peut être utilisée pour le téléchargement ou la lecture. Le fait que le lien audio soit accessible ne prouve pas que les autres candidats disposent également de l’éligibilité à l’exportation du projet.

Erreurs et récupération

Les projets et les candidats sont liés à l’application qui les a créés ; utilisez l’application d’origine pour y accéder. Conservez durablement l’URL audio finale exportée avec succès et gardez trace_id pour faciliter le dépannage.