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.
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.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
request_body | object | Yes | No parameter description. | — |
request_body.seed | integer | null | No | Random seed for reproducibility. If not provided, a random seed will be used. | — |
request_body.tags | string | Yes | Comma-separated list of genre tags to control the style of the generated audio. | — |
request_body.lyrics | string | No | Lyrics 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.duration | number | No | The duration of the generated audio in seconds. | 60 |
request_body.scheduler | enum (euler | heun) | No | Scheduler to use for the generation process. | euler |
request_body.guidance_type | enum (cfg | apg | cfg_star) | No | Type of CFG to use for the generation process. | apg |
request_body.guidance_scale | number | No | Guidance scale for the generation. | 15 |
request_body.number_of_steps | integer | No | Number of steps to generate the audio. | 27 |
request_body.granularity_scale | integer | No | Granularity scale for the generation process. Higher values can reduce artifacts. | 10 |
request_body.guidance_interval | number | No | Guidance 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_scale | number | No | Tag guidance scale for the generation. | 5 |
request_body.lyric_guidance_scale | number | No | Lyric guidance scale for the generation. | 1.5 |
request_body.minimum_guidance_scale | number | No | Minimum guidance scale for the generation after the decay. | 3 |
request_body.guidance_interval_decay | number | No | Guidance 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.
/agent-api/v1/tool/executeX-Api-KeySubmit first, then query with the returned task_id until the task completes.
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"
}
}
}'{
"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







