How to Add Seedream Image Tools to Gemini CLI with MCP

#ai #devtools #programming #tutorial

Voice cloning demos often skip the part that determines whether the result is usable: preparing a clean source recording and carrying the returned identity into the generation request correctly. This guide walks through that small but important pipeline, from a WAV or MP3 sample to a song generated with its private voice character.

What you are building

The workflow has two API calls against the base URL https://api.acedata.cloud:

POST /suno/voices accepts a public audio_url and creates a voice character.
POST /suno/audios accepts the resulting persona_id together with a music prompt and a supported model.

The handoff between those calls is the key design detail. The cloning response also contains a generated name, but your application should store and reference persona_id. Uploaded voice characters are private resources, and they cannot be reused across accounts.

Before implementing this, make consent part of the product flow. Only clone a voice you own or have explicit permission to use. That is not an API parameter, but it is a sensible boundary for any real application involving someone’s identity.

Step 1: prepare a source recording that can pass verification

The voice endpoint accepts a publicly accessible audio_url pointing to a WAV or MP3 file. The supported duration is 10–240 seconds, while the practical recommendation is a clean 30–60 second sample.

More audio is not automatically better. A short dry recording with one recognizable speaker or singer is preferable to a finished song. Avoid accompaniment, background noise, echo, reverb, multiple speakers, low volume, and unclear speech. Those conditions can cause cloning to fail or reduce the quality of later generations.

In production, I would validate the file format and duration before submitting the request. I would also tell the user why a studio-like dry sample matters rather than returning a generic error after a long upload.

Step 2: create the private voice character

Send the source file URL in audio_url. The name and description fields are optional.

curl -X POST 'https://api.acedata.cloud/suno/voices' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "audio_url": "{public_wav_or_mp3_url}",
    "name": "My Voice",
    "description": "Single clear voice example"
  }'

A successful response follows this shape:

{
  "success": true,
  "task_id": "0fa609a6-c8d9-4bb5-8574-e4c93bb55d02",
  "data": {
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16",
    "name": "VOICE_20260803037676",
    "is_public": false
  }
}

Persist data.persona_id; do not treat the generated name as the stable reference. The is_public value is false for a voice character created from uploaded audio.

Voice cloning is compute-intensive, so a compliant sample can occasionally return a failure such as voices_sound_different. The integration guidance recommends one or two automatic retries, including when retrying the same material. Keep that retry policy bounded: record the failure, retry briefly, and then ask for a cleaner sample instead of hiding a persistent input problem. Failed requests are not charged according to the integration document.

Step 3: generate music with the cloned voice

Pass the stored identifier to the audio generation endpoint. Set action to generate, include a text prompt, and choose a compatible model. Voice cloning works with chirp-v4-5 and later models such as chirp-v5 and chirp-v5-5; it does not support chirp-v4.

curl -X POST 'https://api.acedata.cloud/suno/audios' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "chirp-v5-5",
    "prompt": "A warm synth-pop song about city nights",
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16"
  }'

The returned data is an array. Each generated item can include fields such as id, title, audio_url, image_url, model, state, prompt, and duration. For an application, I would wait for state to be succeeded before exposing audio_url, and keep the original prompt beside the result so users can understand what produced it.

The same persona_id can also be used with the cover action, but starting with generate keeps the first integration easy to reason about: one owned source voice, one stored identifier, and one explicit music prompt.

A small production checklist

Validate WAV or MP3 and the 10–240 second duration range before calling the API.
Prefer a 30–60 second dry, single-voice sample.
Send bearer authentication in the authorization header.
Store persona_id, not the automatically generated voice name.
Use chirp-v4-5 or a later supported model.
Limit cloning retries to one or two attempts and surface actionable feedback.
Keep the voice resource and generated output tied to the account that created them.

What I like about this workflow is that it stays understandable: the first request creates an identity token, and the second uses that token as one input to generation. If you are implementing it yourself, keep the consent and audio-quality checks as visible as the API calls; the full field-level reference is in the Ace Data Cloud voice cloning integration guide.

DEV Community