Ace Step

Usage-based pricing
ae_ace_step

Generate audio from text using the ACE-Step model. This asynchronous AE call returns an AE task_id. You must use ae_get_result with that same task_id to check progress and retrieve the result. If still processing, query the same task_id again; do not resubmit the generation request. seed is optional and accepts only an integer or null. Omit seed or set it to null to use a random seed; the string "random" is not supported.

Audio
Usage-based pricing

Pricing

The charge per call is (max(0.24 × successfully generated audio duration (seconds), 0)) AE credits. All applicable conditions are combined to calculate the total.

Parameters

Optional parameters use the platform defaults when omitted.

ParameterTypeRequiredDescriptionDefault
request_bodyobjectYesNo parameter description.—
request_body.seedinteger | nullNoRandom seed for reproducibility. If not provided, a random seed will be used.—
request_body.tagsstringYesComma-separated list of genre tags to control the style of the generated audio.—
request_body.lyricsstringNoLyrics to be sung in the audio. If not provided or if [inst] or [instrumental] is the content of this field, no lyrics will be sung. Use control structures like [verse], [chorus] and [bridge] to control the structure of the song.""
request_body.durationnumberNoThe duration of the generated audio in seconds.60
request_body.schedulerenum (euler | heun)NoScheduler to use for the generation process.euler
request_body.guidance_typeenum (cfg | apg | cfg_star)NoType of CFG to use for the generation process.apg
request_body.guidance_scalenumberNoGuidance scale for the generation.15
request_body.number_of_stepsintegerNoNumber of steps to generate the audio.27
request_body.granularity_scaleintegerNoGranularity scale for the generation process. Higher values can reduce artifacts.10
request_body.guidance_intervalnumberNoGuidance interval for the generation. 0.5 means only apply guidance in the middle steps (0.25 * infer_steps to 0.75 * infer_steps)0.5
request_body.tag_guidance_scalenumberNoTag guidance scale for the generation.5
request_body.lyric_guidance_scalenumberNoLyric guidance scale for the generation.1.5
request_body.minimum_guidance_scalenumberNoMinimum guidance scale for the generation after the decay.3
request_body.guidance_interval_decaynumberNoGuidance interval decay for the generation. Guidance scale will decay from guidance_scale to min_guidance_scale in the interval. 0.0 means no decay.0

Invocation example

Copy the request and explore its response example.

POST/agent-api/v1/tool/executeX-Api-Key

Submit first, then query with the returned task_id until the task completes.

Request coderequest.sh
curl --request POST \
  --url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_ace_step' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "params": {
    "request_body": {
      "duration": 5,
      "lyrics": "[inst]",
      "number_of_steps": 3,
      "tags": "soft instrumental piano"
    }
  }
}'
Response exampleresponse.json
JSON
{
  "description": "task accepted; poll the result via query_tool with this task_id",
  "query_tool": "ae_get_result",
  "status": "created",
  "task_id": "6aa11777-2000-4e47-9657-9c12479dc354"
}

Guides using this tool

See how this tool fits into real workflows