DEV Community

Cover image for How to Upload Reference Audio for a Suno-Based Music Workflow
Germey
Germey

Posted on • Originally published at platform.acedata.cloud

How to Upload Reference Audio for a Suno-Based Music Workflow

#ai #api #tutorial #devtools

When you build music features, the first useful primitive is often not “generate a full song from scratch.” It is: take an existing reference track, upload it safely, extract the metadata you need, and keep the returned song ID for the next step in your workflow.

Cover image for Suno Upload API

This guide walks through the Suno Upload Reference Audio API on Ace Data Cloud. The API is intentionally small: send a publicly accessible MP3 URL, receive an uploaded audio record, and use the returned audio_id later for secondary creation.

What you can do

The upload endpoint is:

Base URL: https://api.acedata.cloud
Endpoint: POST /suno/upload
Headers:
  accept: application/json
  authorization: Bearer {token}
  content-type: application/json
Enter fullscreen mode Exit fullscreen mode

The request body has one input parameter:

{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3"
}
Enter fullscreen mode Exit fullscreen mode

The important constraint is that audio_url must be a publicly accessible CDN address and support the .mp3 suffix. In other words, this endpoint is best used after your app has already placed the reference audio somewhere the API can fetch.

The response gives you a normalized audio object. The key field is data.audio_id, which is the song ID after upload. The response can also include extracted or generated context such as lyric, style, image_url, image_large_url, audio_url, title, and duration.

Step 1: Make the upload request

Here is the complete cURL call from the integration shape:

curl -X POST 'https://api.acedata.cloud/suno/upload' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3"
  }'
Enter fullscreen mode Exit fullscreen mode

In a real application, replace the demo URL with a direct MP3 URL from your own storage or CDN. I would validate three things before calling the API:

  1. The URL is reachable without user authentication.
  2. The file is an MP3 URL, not a web page that embeds a player.
  3. Your backend stores the original source URL before sending the request.

That third point matters because the returned data tells you what the platform produced, while the source URL tells you what your user originally provided.

Step 2: Read the response as a workflow object

A successful response has this general shape:

{
  "success": true,
  "task_id": "058f8450-3df4-4f8b-8b64-ebc2e59ed3bc",
  "data": {
    "audio_id": "00135f7d-cda1-4d70-b007-779f07143586",
    "lyric": "[Intro]\nHa-ha-ha-ha-ha-ha...",
    "style": "Upbeat bubblegum pop track with a high-energy electronic production style...",
    "image_url": "https://cdn2.suno.ai/image_00135f7d-cda1-4d70-b007-779f07143586.jpeg",
    "image_large_url": "https://cdn2.suno.ai/image_large_00135f7d-cda1-4d70-b007-779f07143586.jpeg",
    "audio_url": "https://cdn1.suno.ai/00135f7d-cda1-4d70-b007-779f07143586.mp3",
    "title": "up-d6c3970d-6db1-41e3-b966-90539c93678a",
    "duration": 131.16
  }
}
Enter fullscreen mode Exit fullscreen mode

The fields I would persist are:

  • task_id for tracking the upload request
  • data.audio_id for later music generation or extension flows
  • data.audio_url for playback
  • data.duration for UI display and validation
  • data.lyric and data.style if your product lets users review or edit the extracted musical context

Treat the upload response as the “asset registration” step. After this, your app has an ID it can pass to later music-generation operations.

Step 3: Connect it to secondary creation

The document notes that once you have the song ID, you can use the Suno Audios Generation API to generate custom songs. The specific handoff is to pass action as upload_extend and use the returned audio_id as the reference song ID.

A clean backend abstraction might look like this:

uploadReferenceAudio({ audio_url }) -> { task_id, audio_id, lyric, style, audio_url, duration }
Enter fullscreen mode Exit fullscreen mode

Then the next workflow step can accept audio_id without needing to know where the original file came from.

This separation helps a lot in product code. Uploading reference audio, reviewing extracted context, and generating a derivative song are different user actions. Keeping them separate makes the interface easier to debug and easier to retry.

Step 4: Design the user flow around constraints

Because the API expects a public MP3 URL, your user-facing flow should make that constraint obvious. A practical flow is:

  1. User uploads an MP3 to your app.
  2. Your backend stores it on a CDN or object storage bucket.
  3. Your backend calls POST /suno/upload with the public audio_url.
  4. Your app displays the returned title, duration, cover image, lyric, and style.
  5. The user confirms whether to continue with a secondary creation step using audio_id.

If the upload fails, keep the original user file and source URL so the user does not have to start again. If the upload succeeds but later generation fails, you still have audio_id and can retry the downstream step.

A small but useful primitive

This endpoint is deliberately narrow, and that is what makes it useful. It does not ask you to model the entire music workflow in one request. It gives you one reliable bridge from an existing MP3 reference to an audio_id that can be used later.

For builders, that is a good boundary: one API call to register the reference, one stored ID for future work, and enough metadata to show users what was understood from their audio.

The full field reference is in the Suno Upload API documentation: https://platform.acedata.cloud/documents/suno-upload-integration

Top comments (0)