apimaxDocs
文档定价控制台
API 参考接入指南用户指南更新日志

音乐系列

DOCNew-api兼容Suno格式

图像系列

视频系列

任务管理

错误码参考查询任务状态GET

账户管理

查询额度使用情况GET

文档 / 音乐系列 / Suno / NewAPI兼容

NewAPI兼容new-apiSunoNative FormatAsync TasksAPI

New-api兼容Suno格式

new-api 兼容的 Suno 格式使用 /suno/submit/{ACTION} 提交任务，并通过 /suno/fetch 查询结果。

APIhttps://api.apimax.ai/suno/submit/{action}
试一试
Bearer API KeyJSON服务端调用

概述#

new-api 兼容的 Suno 调用格式以 /suno/* 为前缀。创建音乐、歌词或音频二次加工任务时，统一使用：

http
POST /suno/submit/{ACTION}

其中 {ACTION} 表示任务类型，例如 MUSIC、LYRICS、WAV、MP4。提交成功后接口立即返回公开 task_id，再通过 /suno/fetch 查询任务状态和结果。

new-api Suno 的核心调用链是：POST /suno/submit/{ACTION} 提交任务，GET /suno/fetch/{task_id} 或 POST /suno/fetch 查询结果。

本站另外提供 /suno/* OpenAI 风格便捷入口，但它不是本文所说的 new-api Suno 格式。需要兼容现有 new-api Suno 客户端时，请使用本文的 /suno/* 路径。

Base URL#

本文示例使用：

text
https://api.apimax.ai

完整的音乐生成地址为：

text
https://api.apimax.ai/suno/submit/MUSIC

不要在 /suno 前重复添加 /v1。以下地址不是 new-api Suno 提交路径：

text
/v1/suno/submit/MUSIC
/v1/music/generations

鉴权#

所有 /suno/* 请求都使用本站 API Key：

http
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

API Key 可在本站 API Key 页面 创建。请使用完整密钥，包括 sk- 前缀。

API Key 只能保存在服务端，不要写入浏览器前端、公开仓库或客户端安装包。

提交端点#

http
POST /suno/submit/{ACTION}

路径中的 action 不区分大小写，服务端会统一转成大写。为了便于阅读和与文档保持一致，建议始终使用大写 action。

支持的 action#

action用途核心输入
MUSIC生成音乐、续写音乐或复用音色生成gpt_description_prompt 或 prompt 等
LYRICS生成歌词prompt
WAV获取 WAV 无损音频clip_id
MP4获取音乐视频clip_id
SPEED调整音频速度clip_id、speed_multiplier
TIMING获取歌词时间轴clip_id
CROP裁剪音频clip_id、crop_start_s、crop_end_s
MIDI获取 MIDIclip_id
FADE添加淡入淡出clip_id，以及至少一个淡入或淡出时间
CONCAT合并或延长片段clip_id
REVERSE倒放音频clip_id
REMASTER重制或升采样clip_id
WAVEFORM获取波形数据clip_id
DOWNBEATS获取节拍点分析clip_id
RECUT版权音频切段重组clip_id

未知 action 会返回 400 和 invalid_action。

生成音乐#

描述模式#

描述想要的音乐，Suno 自动生成歌词和歌曲：

cURL
curl --request POST \
  --url https://api.apimax.ai/suno/submit/MUSIC \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "gpt_description_prompt": "一首轻快的夏日流行歌曲，女声，主题是海边日落",
    "make_instrumental": false,
    "mv": "chirp-v3-0"
  }'

自定义歌词模式#

自己提供歌词、标题和风格标签：

cURL
curl --request POST \
  --url https://api.apimax.ai/suno/submit/MUSIC \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "[Verse]\n晚风穿过安静的街\n[Chorus]\n我们奔向海岸线",
    "title": "海岸线",
    "tags": "pop, female vocal, uplifting",
    "make_instrumental": false,
    "mv": "chirp-v3-0"
  }'

MUSIC 常用字段#

字段类型必填说明
gpt_description_promptstring二选一自然语言音乐描述，适合自动歌词模式
promptstring二选一自定义歌词，可包含 [Verse]、[Chorus] 等段落标记
titlestring否歌曲标题
tagsstring否风格、流派、情绪和人声标签
mvstring否Suno 模型版本，缺省时使用 chirp-v3-0
make_instrumentalbool否是否生成纯伴奏
continue_clip_idstring否续写时引用的源 clip ID
continue_atnumber否从源音频多少秒处开始续写
persona_idstring否使用已创建的人声音色
taskstring否扩展任务类型，例如 vox、gen_stem
stem_taskstring否分轨类型，例如 two 或 twelve
notify_hookstring否任务终态回调地址

生成歌词#

cURL
curl --request POST \
  --url https://api.apimax.ai/suno/submit/LYRICS \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "写一首关于雨夜重逢的中文流行歌词"
  }'

LYRICS 必须提供非空 prompt，否则返回 prompt_empty。

二次加工示例#

获取 WAV#

cURL
curl --request POST \
  --url https://api.apimax.ai/suno/submit/WAV \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "clip_id": "11f1b88e-xxxxxxxxxxxxxxxxxxxxxxxx"
  }'

调整速度#

cURL
curl --request POST \
  --url https://api.apimax.ai/suno/submit/SPEED \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "clip_id": "11f1b88e-xxxxxxxxxxxxxxxxxxxxxxxx",
    "speed_multiplier": 1.15,
    "keep_pitch": true
  }'

裁剪音频#

cURL
curl --request POST \
  --url https://api.apimax.ai/suno/submit/CROP \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "clip_id": "11f1b88e-xxxxxxxxxxxxxxxxxxxxxxxx",
    "crop_start_s": 10,
    "crop_end_s": 35,
    "is_crop_remove": false
  }'

crop_end_s 必须大于 crop_start_s。

添加淡入淡出#

cURL
curl --request POST \
  --url https://api.apimax.ai/suno/submit/FADE \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "clip_id": "11f1b88e-xxxxxxxxxxxxxxxxxxxxxxxx",
    "fade_in_time": 2.5,
    "fade_out_time": 3
  }'

fade_in_time 和 fade_out_time 至少提供一个。

提交响应#

所有 /suno/submit/{ACTION} 成功后都返回统一结构：

200
{
  "code": "success",
  "message": "",
  "data": "task_01Jxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

data 是本站公开任务 ID。后续查询、回调关联和问题排查都使用该 ID，不要使用上游内部任务 ID。

提交成功只表示任务已经创建，不代表音乐、歌词或加工结果已经完成。

查询单个任务#

推荐使用与 new-api Suno 格式对应的查询路径：

http
GET /suno/fetch/{task_id}
cURL
curl --request GET \
  --url https://api.apimax.ai/suno/fetch/task_01Jxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx'

响应结构：

200
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_01Jxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "platform": "suno",
    "action": "MUSIC",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "submit_time": 1780000000,
    "start_time": 1780000005,
    "finish_time": 1780000120,
    "data": [
      {
        "id": "clip_xxx",
        "audio_url": "https://example.com/audio.mp3",
        "video_url": "https://example.com/video.mp4",
        "image_url": "https://example.com/cover.jpeg",
        "title": "海岸线"
      }
    ]
  }
}

任务可能出现以下状态：

状态说明
NOT_START / SUBMITTED / QUEUED已创建或正在排队
IN_PROGRESS上游处理中
SUCCESS任务成功，读取 data.data
FAILURE任务失败，读取 data.fail_reason

批量查询任务#

http
POST /suno/fetch
cURL
curl --request POST \
  --url https://api.apimax.ai/suno/fetch \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "ids": [
      "task_01Jxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "task_01Kyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
    ]
  }'

批量查询的 data 是任务数组。不存在或不属于当前用户的 ID 不会泄露任务数据。

本站也提供通用任务查询端点：

http
GET /v1/tasks/{task_id}

但现有 new-api Suno 客户端迁移时，继续使用 /suno/fetch 即可。

终态回调#

提交请求中可以传入 notify_hook：

json
{
  "gpt_description_prompt": "一首舒缓的钢琴纯音乐",
  "make_instrumental": true,
  "notify_hook": "https://your-service.example.com/webhooks/suno"
}

任务进入 SUCCESS 或 FAILURE 后，本站会向该地址发送终态结果。回调地址必须是公网可访问的 HTTPS 地址，接收方应按 task_id 做幂等处理，并保留 /suno/fetch 轮询作为兜底。

/suno/submit/* 之外的 Suno 路径#

下面这些能力不是 submit action，使用独立的 /suno/* 路径：

路径方法类型用途
/suno/upload/audioPOST异步上传音频并导入为 Suno clip
/suno/voice/samplePOST异步上传演唱样本
/suno/voice/createPOST异步验证并创建音色
/suno/voice/from-clipPOST异步从已有歌曲创建音色
/suno/recutPOST异步版权音频切段重组
/suno/upload/filePOST同步上传或转存文件并直接返回结果
/suno/prompts/suggestionsGET同步获取风格灵感建议
/suno/prompts/upsamplePOST同步润色风格或标签

异步独立路径返回的任务同样通过 /suno/fetch 查询。

/suno/* 是什么#

new-api 网关同时保留了一组 /suno/* 路由，用于给偏好 OpenAI 风格参数的客户端提供便捷入口。例如：

text
POST /v1/music/generations
POST /suno/submit/WAV

这些入口最终也会转换或转发到 Suno 任务系统，但它们属于额外的 OpenAI 风格封装。本文档的 new-api Suno 兼容格式以 /suno/submit/{ACTION} 和 /suno/fetch 为准。

常见错误#

HTTPcode / 原因处理建议
400invalid_action检查 /suno/submit/{ACTION} 中的 action
400prompt_emptyLYRICS 请求补充 prompt
400clip_id_empty二次加工请求补充 clip_id
400speed_multiplier_emptySPEED 请求补充 speed_multiplier
400crop_range_empty / crop_range_invalid检查裁剪起止时间
400fade_time_empty至少提供一个淡入或淡出时间
401API Key 无效检查完整 Authorization: Bearer sk-...
503无可用渠道稍后重试或联系管理员

不要根据提交接口返回 200 就判断生成完成。必须持续查询到 SUCCESS 或 FAILURE，或者等待终态回调。

下一步

全部文档
Relink 音频链接根据 Suno clip_id 同步获取可直接使用的音频链接。润色风格标签把风格标签和歌词润色扩写成更完整的风格描述。获取风格灵感建议获取 Suno 上游的随机风格或灵感建议。方法一:从已有歌曲创建音色使用本池已生成的歌曲 clip 直接创建人声音色。上传音频把用户音频导入为 Suno 自有 clip，返回异步上传任务 ID；带 copyright=true 时改走版权音乐管线。查询额度使用情况使用 API Key 查询当前令牌及所属用户的剩余 credits、已用 credits 和无限额度状态。
本页导航
概览概述Base URL鉴权提交端点支持的 action生成音乐描述模式自定义歌词模式MUSIC 常用字段生成歌词二次加工示例获取 WAV调整速度裁剪音频添加淡入淡出提交响应查询单个任务批量查询任务终态回调/suno/submit/ 之外的 Suno 路径/suno/ 是什么常见错误下一步
API

API /suno/submit/{action}