生产接口 API 文档

本文按“任务 / 媒体与工具 / 计费”三组整理常用生产接口。

所有示例都使用生产域名 https://sunocore.sunoai.asia，并默认通过 X-API-Key 鉴权。

1. 通用说明

1.1 Base URL

https://sunocore.sunoai.asia

1.2 请求头

X-API-Key: <your_api_key>
Content-Type: application/json

1.3 异步任务通用规则

以下接口会先返回一个 task_id，实际结果需要后续查询：

POST /suno/submit/music
POST /suno/submit/upsample
POST /suno/uploads/audio-url
POST /suno/submit/concat
POST /suno/submit/speed-adjust
POST /api/crop

通用返回示例：

{
  "code": "success",
  "message": "",
  "data": "8d0a9b37-22e0-4543-94ca-7ce3de3fd27f"
}

推荐调用顺序：

提交任务，拿到 task_id
使用 POST /suno/fetch 批量轮询
或使用 GET /suno/fetch/{task_id} 查询单个任务

1.4 常见错误码

状态码	说明
`400`	参数缺失或参数格式错误
`401`	API Key 无效或缺少鉴权头
`402`	余额不足
`403`	当前 Key 无权限调用该接口
`404`	任务、歌曲或 clip 不存在
`429`	触发限流或并发限制
`502`	上游实例不可用

2. 生产接口 / 任务

2.1 提交音乐生成任务

接口

POST /suno/submit/music

说明

用于提交标准音乐生成任务。
也支持 extend、cover 等特殊创作场景。
成功后立即返回新的 task_id。

常用参数

参数	类型	必填	说明
`title`	`string`	否	歌曲标题
`tags`	`string`	否	风格标签
`prompt`	`string`	否	歌词或创作提示词
`negative_tags`	`string`	否	不希望出现的风格
`mv`	`string`	否	模型，如 `chirp-crow`
`make_instrumental`	`boolean`	否	是否生成纯音乐
`task`	`string`	否	特殊任务类型，如 `extend`、`cover`
`task_id`	`string`	否	特殊任务依赖的原任务 ID
`continue_clip_id`	`string`	否	续写目标 clip ID
`cover_clip_id`	`string`	否	翻唱目标 clip ID
`metadata`	`object`	否	扩展控制参数

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/submit/music' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Midnight Drive",
    "tags": "synthwave, neon, energetic",
    "prompt": "A night drive song with bright synths and a strong chorus.",
    "negative_tags": "lofi",
    "mv": "chirp-crow",
    "make_instrumental": false
  }'

2.2 批量查询任务状态

接口

POST /suno/fetch

参数说明

参数	类型	必填	说明
`ids`	`string[]`	是	要查询的任务 ID 列表
`action`	`string`	否	兼容旧客户端的保留字段，可不传

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/fetch' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [
      "8d0a9b37-22e0-4543-94ca-7ce3de3fd27f"
    ]
  }'

返回重点

字段	说明
`task_id`	任务 ID
`status`	任务状态，如 `IN_PROGRESS`、`SUCCESS`、`FAILURE`
`progress`	进度百分比
`data`	产物列表，常见含 `clip_id`、`audio_url`、`image_url`、`video_url`

2.3 查询单个任务状态

接口

GET /suno/fetch/{task_id}

路径参数

参数	说明
`task_id`	要查询的任务 ID

curl 示例

curl -X GET 'https://sunocore.sunoai.asia/suno/fetch/8d0a9b37-22e0-4543-94ca-7ce3de3fd27f' \
  -H 'X-API-Key: sk_xxx'

2.4 创建音频上传地址

接口

POST /suno/api/create_audio_upload

说明

用于上传类任务的第一步。
返回 upload_id、上传地址和表单字段。
上传完成后，再调用 POST /suno/uploads/audio-url。

参数说明

参数	类型	必填	说明
`extension`	`string`	是	文件后缀，如 `mp3`、`wav`

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/api/create_audio_upload' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "extension": "mp3"
  }'

2.5 提交音频上传处理任务

接口

POST /suno/uploads/audio-url

说明

推荐配合上传地址接口使用。
成功后返回新的 task_id。

常用参数

参数	类型	必填	说明
`upload_id`	`string`	是	上传会话 ID
`upload_filename`	`string`	是	上传文件名，不带扩展名也可以
`wait_audio`	`boolean`	否	是否等待音频处理完成，默认 `true`

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/uploads/audio-url' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "upload_id": "8b2da18a-dd8c-43f9-8053-88f206958494",
    "upload_filename": "demo-upload",
    "wait_audio": true
  }'

2.6 提交音频增强任务

接口

POST /suno/submit/upsample

说明

基于已有歌曲提交 Remaster / Upsample。
成功后返回新的 task_id。

参数说明

参数	类型	必填	说明
`task_id`	`string`	是	原任务 ID
`clip_id`	`string`	是	要增强的 clip ID
`model_name`	`string`	否	增强模型，如 `chirp-carp`
`variation_category`	`string`	否	变化强度，如 `normal`

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/submit/upsample' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "11111111-2222-3333-4444-555555555555",
    "clip_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "model_name": "chirp-carp",
    "variation_category": "normal"
  }'

2.7 提交歌曲续写任务

接口

POST /suno/submit/concat

说明

用于合并续写结果。
也可用于部分 infill 类场景。

参数说明

参数	类型	必填	说明
`clip_id`	`string`	是	要处理的 clip ID
`is_infill`	`boolean`	否	是否按 infill 逻辑处理

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/submit/concat' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "clip_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "is_infill": false
  }'

2.8 提交调速任务

接口

POST /suno/submit/speed-adjust

参数说明

参数	类型	必填	说明
`clip_id`	`string`	是	要调速的 clip ID
`speed_multiplier`	`number`	是	速度倍率，如 `1.25`
`keep_pitch`	`boolean`	否	是否保持音高
`title`	`string`	否	新任务标题
`task_id`	`string`	否	原任务 ID，用于优先命中同实例

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/submit/speed-adjust' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "clip_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "speed_multiplier": 1.25,
    "keep_pitch": true,
    "title": "Midnight Drive (1.25x)",
    "task_id": "11111111-2222-3333-4444-555555555555"
  }'

2.9 提交裁剪任务

接口

POST /api/crop

参数说明

参数	类型	必填	说明
`task_id`	`string`	是	原任务 ID
`song_id`	`string`	是	歌曲 ID
`crop_start_s`	`number`	是	裁剪开始秒数
`crop_end_s`	`number`	是	裁剪结束秒数
`is_crop_remove`	`boolean`	否	是否移除中间片段

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/api/crop' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "11111111-2222-3333-4444-555555555555",
    "song_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "crop_start_s": 12.5,
    "crop_end_s": 28.0,
    "is_crop_remove": false
  }'

3. 生产接口 / 媒体与工具

3.1 生成歌曲视频

接口

GET /suno/act/mp4/{clip_id}

路径参数

参数	说明
`clip_id`	歌曲 clip ID

curl 示例

curl -X GET 'https://sunocore.sunoai.asia/suno/act/mp4/66666666-7777-8888-9999-aaaaaaaaaaaa' \
  -H 'X-API-Key: sk_xxx'

3.2 创建 Persona

接口

POST /suno/persona/create

常用参数

参数	类型	必填	说明
`root_clip_id`	`string`	建议传	参考歌曲 clip ID
`clips`	`string[]`	建议传	参考 clip 列表
`name`	`string`	是	Persona 名称
`description`	`string`	否	简短描述
`is_public`	`boolean`	否	是否公开
`persona_type`	`string`	否	类型；创建 Vox Persona 时可传 `vox`

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/persona/create' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "root_clip_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "clips": [
      "66666666-7777-8888-9999-aaaaaaaaaaaa"
    ],
    "name": "Demo Persona",
    "description": "Warm pop vocal reference",
    "is_public": true
  }'

3.3 获取 MIDI（任务感知）

接口

GET /suno/midi/{task_id}/{clip_id}

路径参数

参数	说明
`task_id`	任务 ID，用于优先命中原实例
`clip_id`	歌曲 clip ID

curl 示例

curl -X GET 'https://sunocore.sunoai.asia/suno/midi/11111111-2222-3333-4444-555555555555/66666666-7777-8888-9999-aaaaaaaaaaaa' \
  -H 'X-API-Key: sk_xxx'

3.4 获取歌词时间戳

接口

GET /api/get_aligned_lyrics_v3

Query 参数

参数	类型	必填	说明
`song_id`	`string`	是	歌曲 ID 或 clip ID

curl 示例

curl -X GET 'https://sunocore.sunoai.asia/api/get_aligned_lyrics_v3?song_id=66666666-7777-8888-9999-aaaaaaaaaaaa' \
  -H 'X-API-Key: sk_xxx'

3.5 创建歌单并添加歌曲

接口

POST /api/playlist/create_with_clips

参数说明

参数	类型	必填	说明
`task_id`	`string`	是	任意可定位实例的任务 ID
`name`	`string`	是	歌单名称
`clip_ids`	`string[]`	是	要加入歌单的歌曲 ID 列表

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/api/playlist/create_with_clips' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "11111111-2222-3333-4444-555555555555",
    "name": "Inspiration Pack",
    "clip_ids": [
      "clip_a",
      "clip_b"
    ]
  }'

3.6 增强标签描述

接口

POST /api/generate/upsample-tags

参数说明

参数	类型	必填	说明
`original_tags`	`string`	是	原始风格标签

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/api/generate/upsample-tags' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_tags": "lofi chill piano"
  }'

3.7 提示词生成图片

接口

POST /suno/prompt_image

参数说明

参数	类型	必填	说明
`prompt`	`string`	是	图片描述提示词

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/prompt_image' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "retro sci-fi album cover, cinematic lighting, silver robot singer"
  }'

返回重点

字段	说明
`image_url`	图片地址
`image_s3_id`	图片存储 ID

3.8 创建 Vox Persona

接口

POST /suno/persona/create-with-vox-stem

说明

用于有人声歌曲的人声 Persona 提取。
一般比普通同步接口更慢，适合耐心等待返回。

参数说明

参数	类型	必填	说明
`task_id`	`string`	是	原任务 ID，用于命中对应实例
`song_id`	`string`	是	歌曲 ID
`duration`	`number`	是	提取时长，单位秒

curl 示例

curl -X POST 'https://sunocore.sunoai.asia/suno/persona/create-with-vox-stem' \
  -H 'X-API-Key: sk_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_id": "11111111-2222-3333-4444-555555555555",
    "song_id": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "duration": 30
  }'

4. 生产接口 / 计费

4.1 查看定价表

接口

GET /suno/billing/pricing

请求参数

无。

返回重点

字段	说明
`action`	动作编码
`display_name`	展示名称
`price`	单次价格
`enabled`	是否启用
`refund_on_failure`	失败是否退款

curl 示例

curl -X GET 'https://sunocore.sunoai.asia/suno/billing/pricing' \
  -H 'X-API-Key: sk_xxx'

4.2 查看当前计费身份

接口

GET /suno/billing/me

说明

返回当前调用身份。
如果是 API Key 调用，会返回当前 Key 的余额与限额信息。

返回重点

字段	说明
`auth_type`	当前身份类型，如 `api_key`
`is_admin`	是否管理员
`api_key`	当前 Key 信息对象
`api_key.credits_balance`	当前余额
`api_key.rate_limit_per_minute`	每分钟限流
`api_key.concurrency_limit`	并发上限

curl 示例

curl -X GET 'https://sunocore.sunoai.asia/suno/billing/me' \
  -H 'X-API-Key: sk_xxx'

4.3 查看当前 Key 的消费记录

接口

GET /suno/billing/transactions

Query 参数

参数	类型	必填	说明
`limit`	`number`	否	返回条数上限，默认 `100`，最大 `500`

返回重点

字段	说明
`task_id`	关联任务 ID
`action`	对应动作
`change_amount`	本次积分变动
`balance_after`	变动后余额
`transaction_type`	流水类型，如 `CONSUME`、`REFUND`
`created_at`	创建时间

curl 示例

curl -X GET 'https://sunocore.sunoai.asia/suno/billing/transactions?limit=50' \
  -H 'X-API-Key: sk_xxx'

Suno API 官方参考文档

生产接口 API 文档

1. 通用说明

1.1 Base URL

1.2 请求头

1.3 异步任务通用规则

1.4 常见错误码

2. 生产接口 / 任务

2.1 提交音乐生成任务

2.2 批量查询任务状态

2.3 查询单个任务状态

2.4 创建音频上传地址

2.5 提交音频上传处理任务

2.6 提交音频增强任务

2.7 提交歌曲续写任务

2.8 提交调速任务

2.9 提交裁剪任务

3. 生产接口 / 媒体与工具

3.1 生成歌曲视频

3.2 创建 Persona

3.3 获取 MIDI（任务感知）

3.4 获取歌词时间戳

3.5 创建歌单并添加歌曲

3.6 增强标签描述

3.7 提示词生成图片

3.8 创建 Vox Persona

4. 生产接口 / 计费

4.1 查看定价表

4.2 查看当前计费身份

4.3 查看当前 Key 的消费记录