Suno Upload Reference Audio (Ace Data Cloud)

The moment you stop wanting "a song about rain" and start wanting "a song built on this rain" you've left prompt-only generation behind. Suno Upload Reference Audio (Ace Data Cloud) is the door into that mode: you hand the API an audio file, it hands you an ID, and every reference-driven action in the rest of the pack keys off that ID.

Why you'd care: this is the one thing the local music models genuinely can't do. Our KB's audio survey has the API winning clean vocal songs, while ACE-Step - the community's local answer to Suno - is strong on instrumentals and weak on vocals. This node is how you point Suno's vocal tier at your performance: cover, upload_extend, upload_cover and the persona tools all need an audio_id, and only an upload produces one.

How it works

It's a single POST /suno/upload, contract-validated on your machine before it leaves, and that's the whole mechanism - the interesting part is what the client does around it.

First, validation: the pack ships Suno's published schema and runs your payload against it, so a bad mode or a malformed callback_url fails locally instead of round-tripping to the service.

Second, and more important: this call is not retried. The client attempts non-read-only requests exactly once, deliberately - only queries get the three-strike retry. The reasoning is sound (you don't want a half-successful upload resent), but a network drop then leaves you with no idea whether the upload landed. Look it up in the Ace request history by the trace_id before running it again.

The inputs

audio_url is the only required field, and it's the one everybody misreads. It must be a public HTTPS URL that Suno's servers can fetch. Not a path on your disk, not a ComfyUI/input reference, and not the AUDIO type from Preview/Save Audio. Nothing in this pack uploads a local file for you, so if your workflow generates audio on your machine, it has to get that file to a reachable URL first. The Projects endpoint's own upload branch is stricter still, pattern-matching ^https://.

The rest are optional and small:

• mode - standard or enhanced. That enum is the documentation; the pack copies the published schema verbatim, so nothing explains what enhanced does differently or what it costs. Start with standard, and type it exactly - a typo gets you "Invalid mode: does not meet the API's enum constraint" before anything is sent.
• name - a label for the upload, 1 to 100 characters. Bounds are enforced client-side.
• callback_url - only if you're driving it asynchronously and want the service to call you back. It's validated as a URI, so plain text gets rejected.
• parameters_json - a raw JSON object for anything else, with non-empty named fields overriding it.

One rule that isn't in the schema and matters more than the rest: only upload material you have the right to process. The pack's README says it, the privacy notes repeat it, and Suno's own content rules decide what happens next.

Outputs

You get the same six strings as every tool node in this pack: status, task_id, media_urls_json, first_media_url, result_json, trace_id.

The one you need is buried in result_json - that's where the audio_id for your upload shows up, and it's the value you paste into the audio_id field of the cover/extend actions on Suno Generate Audios, or into the persona tools. first_media_url and media_urls_json may carry the uploaded file's own CDN link, and task_id matters if the service answered asynchronously (poll it with Suno Retrieve Task).

There's no AUDIO output. To actually listen to what you uploaded, route a media URL through Suno Load Audio - though that loader only accepts links from the pack's own CDN hosts and refuses redirects, so it won't take an arbitrary third-party URL.

Install

Manager → Custom Nodes → search Suno, publisher acedatacloud, package Suno by Ace Data Cloud (Registry ID ace-suno). If Manager shows nothing - the pack's own test records the Registry not listing it at test time - clone it:

cd ComfyUI/custom_nodes
git clone https://github.com/AceDataCloud/SunoComfyUI.git
cd SunoComfyUI && python -m pip install -r requirements.txt

requirements.txt installs requests and jsonschema (the README's "only adds requests" is stale; jsonschema does the validating, so keep it). No models, no GPU. Then the key, in the environment of the ComfyUI process:

export ACEDATACLOUD_API_KEY='paste-your-key-here'
python main.py

Common issues

HTTP 401/403 covers the key, its Suno access, path restrictions, and content policy refusals - the last being most likely if the file is somebody else's song. HTTP 429 is the rate limit; wait. HTTP 5xx is the annoying one: because there's no retry by design, check the Ace request history for that trace ID before resubmitting, or you risk a duplicate upload you'll have to reconcile by hand. And if the status looks fine but a later fetch fails, check that the link you supplied is still publicly reachable - Suno fetched it once, at upload time.