Saltar al contenido principal
POST https://api.acedata.cloud/suno/projects es la interfaz Beta para gestionar proyectos multipista. Se distinguen la creación, guardado, generación de candidatos, envío de candidatos y exportación mediante action.
Excepto retrieve, cada operación requiere Idempotency-Key. La misma clave y la misma solicitud solo vuelven a leer el resultado original; la misma clave con solicitudes diferentes devuelve 409. Cuando una generación con coste encuentra un tiempo de espera de red o el resultado del envío es incierto, primero consulte usando el ID de tarea original o la misma clave de idempotencia; no cambie directamente la clave para reenviar.

Identificadores y unidades de tiempo

start_seconds / end_seconds son segundos dentro del audio fuente; start_beats / end_beats son pulsos en la línea de tiempo del proyecto. state.timing.bps es el número de pulsos por segundo, con un valor predeterminado de 2. Por ejemplo, un fragmento de 41 segundos que comienza en el pulso 0 tiene como punto final predeterminado el pulso 82. El intervalo en segundos de generate_track se usa para especificar la referencia de generación y no garantiza que el candidato tenga solo la duración de dicho intervalo.

Flujo de operaciones

Si solo se realiza un reemplazo local, basta con tener audio fuente disponible y no es necesario ejecutar primero render; si el audio fuente ya está en el proyecto, también se pueden omitir upload y add_track. render_audio_id es solo una referencia obligatoria para generate_track. Al enviar una operación asíncrona, primero se devuelve { "task_id": "...", "trace_id": "..." }, lo cual no indica que la generación haya tenido éxito. Sondeo:
Solo se considera exitoso cuando el registro de tarea tiene finished_at y su response.success es true; cuando response.success=false, lea response.error. Aunque save puede incluir task_id, se completa de forma síncrona dentro de esta interfaz. upload, render, generate_track y replace_section no modifican la versión del proyecto; tras el éxito de save, add_track, commit_candidate y remove_track, se debe obtener el nuevo version_id.

Convenciones de solicitud

Los siguientes ejemplos muestran de forma encadenada la transmisión de ID y versiones entre las operaciones. Las respuestas solo enumeran los campos relacionados con el paso actual; durante la integración, sustituya los ID de ejemplo por los valores de respuesta de la aplicación actual.

Crear y leer proyectos

Crear proyecto: create

Solicitud:
Respuesta:

Leer proyecto: retrieve

Solicitud:```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”: “Piano generado”, “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” } ] } }
{ “action”: “commit_candidate”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “cb0a82c9-aa5b-48cc-9395-0528675fc18d”, “operation_id”: “66a7356f-3b2a-4472-bdfd-f7b973380644”, “candidate_id”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “track_id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “async”: true }
{ “task_id”: “3291bd86-d524-4720-9b6e-655efa600e3d”, “trace_id”: “1bfee6c0-e936-4147-8a75-a903173d13d6” }
{ “success”: true, “task_id”: “3291bd86-d524-4720-9b6e-655efa600e3d”, “trace_id”: “1bfee6c0-e936-4147-8a75-a903173d13d6”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “committed_candidate_id”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “state”: { “tracks”: [ { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9”, “clips”: [ { “clipId”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “startBeats”: 0, “endBeats”: 82 } ] }, { “id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “clips”: [ { “clipId”: “1a4788a8-6f04-47d7-9698-4199b585b9a8”, “startBeats”: 0, “endBeats”: 83.52 } ] } ] } } }
{ “action”: “render”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “title”: “Suno Projects Docs Mix With Piano”, “lyrics”: “[Instrumental]”, “async”: true }
{ “task_id”: “12fe503c-017e-46db-9d99-8cfb861ad4fc”, “trace_id”: “2f376c45-a081-4c2a-b6a5-658401fe8dc0” }
{ “success”: false, “task_id”: “12fe503c-017e-46db-9d99-8cfb861ad4fc”, “trace_id”: “2f376c45-a081-4c2a-b6a5-658401fe8dc0”, “error”: { “code”: “studio_audio_unavailable”, “message”: “A referenced audio is not available for project rendering. Keep the original project and use a supported audio.” } }
{ “action”: “replace_section”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “source_audio_id”: “b21be571-bfe4-47c1-b59c-2abc55c6f9c3”, “model”: “chirp-v5”, “title”: “Documentation Verse Edit”, “tags”: “dreamy Chinese pop”, “prompt”: “[Verse 1]\n晨光洒在海边\n浪花笑得灿烂\n你和我在沙滩\n钟表停止转动\n冰淇淋在融化\n手牵手去散步\n[Chorus]\n风儿轻轻吹过\n心跳不停鼓\n夏天夏天\n时间停在这一天\n笑声回荡\n微蓝天空在身旁”, “replacement_lyrics”: “我们走在海边\n微风吹过晴天”, “start_seconds”: 12, “end_seconds”: 20, “async”: true }
{ “task_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “trace_id”: “9f9c0bec-963d-417f-aaf2-0b7f89e0dcbc” }
{ “success”: true, “task_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “trace_id”: “9f9c0bec-963d-417f-aaf2-0b7f89e0dcbc”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “operation_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “candidates”: [ { “id”: “c486e799-5f89-4db0-b414-3b666e0db2b3”, “title”: “Documentation Verse Edit”, “state”: “complete”, “duration”: 36, “audio_url”: “https://cdn.acedata2.cloud/suno/287a448c0e6099b5e66901f363607bcfcf38d06312c344b03a3486bbb4fe037b.mp3” }, { “id”: “f0b66dff-9f8e-45f2-b441-c94e2ecd3a11”, “title”: “Documentation Verse Edit”, “state”: “complete”, “duration”: 36, “audio_url”: “https://cdn.acedata2.cloud/suno/172227abd70f2201081a8f58e4c3b401f1e75fd0b29c03aa95abdb6689bfd0a5.mp3” } ] } }
{ “action”: “commit_candidate”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “operation_id”: “e742a2d5-35f1-4a43-b351-c6aa5a744c4c”, “candidate_id”: “c486e799-5f89-4db0-b414-3b666e0db2b3”, “track_id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9”, “async”: true }
{ “task_id”: “2261a2a6-d7fb-42ac-ae58-41005cfc8173”, “trace_id”: “25c6e92d-e0b9-4f9b-ba35-434635ec7bb3” }
{ “success”: false, “task_id”: “2261a2a6-d7fb-42ac-ae58-41005cfc8173”, “trace_id”: “25c6e92d-e0b9-4f9b-ba35-434635ec7bb3”, “error”: { “code”: “bad_request”, “message”: “Candidate duration does not match the source or selected section. Keep the original track and inspect the candidate before editing.” } }
{ “action”: “remove_track”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “1ff01ada-e26b-444e-a618-a91f76754360”, “track_id”: “bdec15b5-ce96-43fa-b681-26298e013b06” }
{ “success”: true, “trace_id”: “5df2f4b4-6f09-4006-93bd-ad44f4ccb8c1”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “removed_track_id”: “bdec15b5-ce96-43fa-b681-26298e013b06”, “state”: { “tracks”: [ { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9” } ] } } }
{ “success”: true, “trace_id”: “c7613f9b-6484-47b1-83ff-f8a0c1529d8e”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “state”: { “tracks”: [ { “id”: “b7ee9e97-f517-44d7-af4c-e9dad71498c9” } ] } } }
{ “action”: “render”, “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “title”: “Suno Projects Docs Mix After Remove”, “async”: true }
{ “task_id”: “41c8bcb2-eb98-4da7-8081-7755bcc7be8d”, “trace_id”: “6480a230-7553-4dd1-a8e2-9131dab418a9” }
{ “success”: true, “task_id”: “41c8bcb2-eb98-4da7-8081-7755bcc7be8d”, “trace_id”: “6480a230-7553-4dd1-a8e2-9131dab418a9”, “data”: { “id”: “af0e104a-2a4c-40e0-9c70-7614566824a6”, “version_id”: “c3f650a9-1c49-4e80-88ef-27deb9b16ce8”, “render_id”: “75aaaa5f-e633-4006-9200-98d03f3542af”, “audio_id”: “75aaaa5f-e633-4006-9200-98d03f3542af”, “duration”: 41, “audio_url”: “https://cdn.acedata2.cloud/suno/75aaaa5f-e633-4006-9200-98d03f3542af.m4a” } }