> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Guía de integración del proyecto Suno Studio

> Suno Music Generation API guide - Ace Data Cloud

La API del proyecto Suno Studio gestiona proyectos de música multipista a través de un único punto de entrada:

```http theme={null}
POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

El `action` de la solicitud determina el tipo de operación. La clave principal del Project utiliza uniformemente `id`; `version_id` representa la versión actual del proyecto, y todas las operaciones de modificación y exportación deben enviar la versión más reciente para evitar sobrescrituras simultáneas.

## Resumen de operaciones

| action | Modo | Uso |
| - | - | - |
| `create` | Síncrono | Crear un proyecto vacío |
| `retrieve` | Síncrono | Leer el proyecto y el `state` editable completo |
| `save` | Síncrono | Guardar el estado completo del proyecto |
| `upload` | Asíncrono | Inicializar material que puede añadirse al proyecto desde una URL de audio HTTPS |
| `add_track` | Asíncrono | Añadir audio existente al proyecto |
| `generate_track` | Asíncrono | Generar nuevos candidatos de pista de audio para un intervalo especificado |
| `replace_section` | Asíncrono | Generar candidatos de reemplazo local |
| `commit_candidate` | Asíncrono | Confirmar el candidato seleccionado en el proyecto |
| `remove_track` | Síncrono | Eliminar la pista especificada |
| `render` | Asíncrono | Exportar una canción completa a partir de la versión guardada |

Las operaciones asíncronas devuelven inmediatamente un `task_id`. Utilice la interfaz gratuita `/suno/tasks` para realizar sondeo, o proporcione `callback_url` para recibir resultados finales.

## Crear y leer

```json theme={null}
{
  "action": "create",
  "title": "My Studio Project"
}
```

Todas las operaciones de modificación deben enviar un Header `Idempotency-Key` único. Tras una creación exitosa, el `data.id` de la respuesta es el ID del Project. Un nuevo proyecto vacío podría no tener `version_id` antes del primer guardado.

```json theme={null}
{"action":"retrieve","id":"PROJECT_ID"}
```

La respuesta de lectura contiene el `state` completo. Se recomienda leer primero, luego modificar y guardar basándose en el valor devuelto; no construya manualmente desde cero las estructuras internas de ritmo y pistas.

## Guardar el estado completo

```json theme={null}
{
  "action":"save",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Edited Project",
  "state":{"tracks":[],"timing":{}}
}
```

El primer guardado de un nuevo proyecto vacío puede omitir `version_id`; después de que el primer guardado genere una versión, los guardados posteriores deben enviar el valor más reciente. Si la versión ya ha cambiado, la interfaz devuelve HTTP 409. En este caso, vuelva a realizar `retrieve`, fusione las modificaciones y envíe de nuevo con una nueva clave de idempotencia; no reintente ciegamente la solicitud anterior.

## Cargar y añadir pistas

```json theme={null}
{
  "action":"upload",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "audio_url":"https://cdn.example.com/reference.mp3",
  "async":true
}
```

Una vez completada la carga, el resultado de la tarea devuelve el `audio_id` candidato. Luego añádalo al proyecto:

```json theme={null}
{
  "action": "add_track",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_id": "AUDIO_ID",
  "name": "Backing Vocals"
}
```

## Generar y reemplazar

`generate_track` genera candidatos de pistas de audio para un intervalo del proyecto; `replace_section` devuelve dos candidatos de reemplazo local. Ninguna de las dos operaciones selecciona automáticamente el resultado artístico.

```json theme={null}
{
  "action": "replace_section",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "source_audio_id": "AUDIO_ID",
  "start_seconds": 35.12,
  "end_seconds": 48.76,
  "model": "chirp-v6",
  "replacement_lyrics": "Nuevo fragmento de letra",
  "async": true
}
```

Después de seleccionar un candidato, confírmelo:

```json theme={null}
{
  "action":"commit_candidate",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "operation_id":"OPERATION_ID",
  "candidate_id":"CANDIDATE_ID",
  "track_id":"TRACK_ID"
}
```

Los candidatos están vinculados a la versión del proyecto en el momento de la generación. Si el proyecto ya ha cambiado, los candidatos anteriores no pueden confirmarse directamente.

## Exportar la canción completa

```json theme={null}
{
  "action":"render",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Final Mix",
  "lyrics":"[Instrumental]",
  "async":true,
  "callback_url":"https://example.com/webhooks/suno"
}
```

El servidor lee el estado autorizado del proyecto de la versión especificada y ensambla los parámetros de exportación. El resultado final contiene `render_id`, `audio_id`, `audio_url` y la duración. El proyecto está vinculado al entorno de ejecución en el que fue creado, y no puede migrarse entre entornos ni realizar una conmutación por error automática.

> Solo puede cargar o procesar audio sobre el que tenga derechos legales de uso. La API de proyectos se encuentra actualmente en Beta; conserve las URL de audio finales de los resultados importantes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.