文档 / 音乐系列 / Suno / 辅助功能
辅助功能POSTSunoSPEEDclipsuno_speed
调整音频速度
对已生成 clip 进行变速处理，可选择是否保持音调。
Bearer API KeyJSON服务端调用
用途#
提交一个 变速（SPEED） 任务，对本服务已生成的 clip 做变速处理，生成一个新的 clip。接口为异步模式：服务在校验通过后立即返回公开 task_id，不会等待任务完成。后续通过 GET /v1/tasks/:id 轮询任务状态与结果。
SPEED 基于源 clip_id 与变速倍率 speed_multiplier 工作：它不重新生成音乐，而是对已有 clip 的音频做加速/减速重采样。clip_id 必须来自本服务已生成的任务结果。
SPEED 需要 clip_id 和 speed_multiplier；keep_pitch、title 和 callback_url 为可选字段。
请求字段#
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
clip_id | string | 是 | — | 目标 Suno clip 的 UUID，须来自本服务已生成的任务结果 |
speed_multiplier | number | 是 | — | 变速倍率，常见范围 0.25 到 4；大于 1 加速，小于 1 减速 |
keep_pitch | bool | 否 | false | 是否在变速时保持原音调；false 时音调随速度变化 |
title | string | 否 | — | 新 clip 标题，留空时自动生成 |
callback_url | string | 否 | — | 任务到达终态时的回调通知地址 |
clip_id 与 speed_multiplier 均为必填。clip_id 为空返回 clip_id_empty；speed_multiplier 未传返回 speed_multiplier_empty。注意：speed_multiplier 显式传 0 也属于已设置（保留显式零值语义），但 0 不是有效倍率，建议传 0.25–4 范围内的有效值。
callback_url 必须是公网可访问的 HTTPS 地址，长度不超过 2048 字符；禁止使用本机、内网、回环、链路本地地址，也禁止使用解析到这些地址的域名。
任务完成或失败后，服务会向该地址发送 POST JSON。回调接收端须在 10 秒内返回任意 2xx 状态码；超时、网络错误或非 2xx 响应均视为失败。
失败后会分别等待 1 秒、2 秒和 4 秒重试，连同首次请求最多发送 4 次。接收端应使用任务 ID 做幂等处理，避免重复处理。
请求示例#
cURL
curl --request POST \
--url https://api.apimax.ai/v1/music/speed \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"clip_id": "1f78f8de-4ca6-4375-ae79-46c33a2c97f7",
"speed_multiplier": 1.5,
"keep_pitch": false,
"title": "Faster Version"
}'成功响应#
200
{
"code": "success",
"message": "",
"data": "task_01HV7..."
}响应字段#
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | 响应码，成功固定为 success |
message | string | 提示信息，成功时通常为空 |
data | string | 公开任务 ID（40 字符以内），用于后续查询 |
data 返回公开 task_id，所有后续查询均使用该 ID。
错误码#
| HTTP | code | 场景 |
|---|---|---|
| 400 | clip_id_empty | clip_id 为空，未指定目标 clip |
| 400 | speed_multiplier_empty | 未传 speed_multiplier 变速倍率 |
| 400 | invalid_request | 请求体 JSON 解析失败 |
| 400 | invalid_action | action 不在支持列表内 |
| 503 | no_available_channel | 无可用渠道 |
| 502 | upstream_failed | 任务处理服务请求失败（网络错误等） |
源 clip 不存在或不可用时会返回对应错误。
查询任务结果#
提交成功后，使用返回的 task_id 轮询：
- 单个查询：
GET /v1/tasks/:id
status 枚举#
| 值 | 说明 |
|---|---|
queued | 任务已创建，等待处理 |
in_progress | 任务正在处理 |
completed | 任务处理完成，可读取 data |
failed | 任务处理失败，可读取 error |
completed 和 failed 为终态；其余状态请继续轮询。
查询结果中的 data 字段包含变速生成的新 clip，包括音频地址等信息。
json
{
"created_at": 1785319736,
"data": [
{
"action_config": {
"actions": [
{
"action_type": "add_to_playlist",
"disabled": false,
"visible": true
},
{
"action_type": "like_song",
"disabled": false,
"visible": true
},
{
"action_type": "share_song",
"disabled": false,
"visible": true
},
{
"action_type": "dislike_song",
"disabled": false,
"visible": true
},
{
"action_type": "report_song",
"disabled": false,
"visible": true
},
{
"action_type": "remove_from_playlist",
"disabled": false,
"visible": true
},
{
"action_type": "delete_song",
"disabled": false,
"visible": true
},
{
"action_type": "edit_song_details",
"disabled": false,
"visible": true
},
{
"action_type": "create_hook",
"disabled": false,
"visible": true
},
{
"action_type": "download_song",
"disabled": false,
"visible": true
},
{
"action_type": "download_as_video",
"disabled": false,
"visible": true
},
{
"action_type": "publish_song",
"disabled": false,
"visible": true
},
{
"action_type": "remaster",
"disabled": false,
"visible": true
},
{
"action_type": "remix_extend",
"disabled": false,
"visible": true
},
{
"action_type": "remix_cover",
"disabled": false,
"visible": true
},
{
"action_type": "remix_reuse_style",
"disabled": false,
"visible": true
}
]
},
"allow_comments": true,
"audio_url": "https://cdn1.suno.ai/d65b7a82-0c45-4a00-805b-5800a33102ac.mp3",
"avatar_image_url": "https://cdn1.suno.ai/sAura5.jpg",
"batch_index": 0,
"comment_count": 0,
"created_at": "2026-07-29T10:08:58.577Z",
"display_name": "hfs90bdvpp7d8",
"entity_type": "song_schema",
"flag_count": 0,
"handle": "hfs90bdvpp7d8",
"has_hook": false,
"id": "d65b7a82-0c45-4a00-805b-5800a33102ac",
"image_large_url": "https://cdn2.suno.ai/image_large_db43894e-4ebf-4b25-be2a-cf7c9bcd0d77.jpeg",
"image_url": "https://cdn2.suno.ai/image_db43894e-4ebf-4b25-be2a-cf7c9bcd0d77.jpeg",
"is_contest_clip": false,
"is_following_creator": false,
"is_handle_updated": false,
"is_hidden": false,
"is_liked": false,
"is_persona_root": false,
"is_public": false,
"is_trashed": false,
"is_verified": false,
"major_model_version": "v5.5",
"media_urls": [
{
"content_type": "m4a-opus",
"delivery": "progressive",
"encoding": "1.0.0",
"url": "https://d2lwuy8qc234o3.cloudfront.net/1/clip/d65b7a82-0c45-4a00-805b-5800a33102ac.m4a"
},
{
"content_type": "mp3",
"delivery": "progressive",
"url": "https://cdn1.suno.ai/d65b7a82-0c45-4a00-805b-5800a33102ac.mp3"
}
],
"metadata": {
"can_publish_with_vocal": false,
"can_remix": true,
"duration": 112.45333333333332,
"has_stem": false,
"has_vocal": false,
"is_remix": true,
"model_badges": {
"songcard": {
"dark": {
"background_color": "0000004D",
"border_color": "00000000",
"text_color": "FD429C"
},
"display_name": "v5.5",
"light": {
"background_color": "0000004D",
"border_color": "00000000",
"text_color": "FD429C"
}
},
"songrow": {
"dark": {
"background_color": "FD429C40",
"border_color": "00000000",
"text_color": "FD429C"
},
"display_name": "v5.5",
"light": {
"background_color": "FD429C1A",
"border_color": "00000000",
"text_color": "FD429C"
}
}
},
"prompt": "[Verse 1]\n把背包拉上\n关掉那一盏灯\n桌上的计划\n先让它们等等\n\n窗外的风在催\n像在说快一点\n我想把今天\n交给陌生海边\n\n[Pre-Chorus]\n带上没说完的话\n带上你的笑\n把昨天折起来\n塞进外套\n\n[Chorus]\n去旅行\n去旅行\n把心放轻\n把脚步放轻\n\n去旅行\n去旅行\n一路往前\n就别回头听\n\n[Verse 2]\n车窗外掠过\n一排排树影\n你靠着我肩膀\n睡得很安静\n\n路过小店门口\n买一杯柠檬冰\n我们不赶时间\n只赶去风景\n\n[Pre-Chorus]\n地图可以改\n明天也可以改\n只要你还在\n我就不怕坏\n\n[Chorus]\n去旅行\n去旅行\n把心放轻\n把脚步放轻\n\n去旅行\n去旅行\n一路往前\n就别回头听\n\n[Bridge]\n如果风太大\n就握紧我的手\n如果夜太长\n我陪你慢慢走\n\n把烦恼留在原地\n让它自己醒\n我们在路上\n已经赢了一程\n\n[Chorus]\n去旅行\n去旅行\n把心放轻\n把脚步放轻\n\n去旅行\n去旅行\n一路往前\n就别回头听",
"speed_clip_id": "db43894e-4ebf-4b25-be2a-cf7c9bcd0d77",
"tags": "Mandopop up-tempo with bouncy four-on-the-floor kick, syncopated acoustic guitar, bright synth plucks, and light handclaps; verse keeps it intimate with sparse drums and close-mic lead, pre-chorus lifts with rising strings and stacked harmony, chorus opens wide with chanty doubles and a singback hook. Add reversed swells into each hook, little bell fills between lines, and a glossy, airy mix that feels sunlit and clean.",
"type": "edit_speed",
"uses_latest_model": true
},
"model_name": "chirp-fenix",
"play_count": 0,
"status": "complete",
"title": "我家有喜 (1.5x)",
"upvote_count": 0,
"user_id": "9f183c4b-98b8-4e22-9264-d80d9ee3c85a",
"video_url": ""
}
],
"finished_at": 1785319750,
"id": "task_JQnxr467w2OqcrmHl5GBdtukgUBiWgEK",
"model": "suno_speed",
"object": "task",
"platform": "suno",
"progress": 100,
"started_at": 1785319737,
"status": "completed",
"type": "suno"
}data[] 为变速生成的新 clip 数组：audio_url / image_url 为结果音频与封面地址，media_urls 提供不同格式的媒体地址，metadata.speed_clip_id 指向源 clip，metadata.type 为 edit_speed，metadata.duration 为结果时长（秒）。字段名与结构以实际响应为准。