> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mountsea.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 生成音乐
> 生成、延伸、翻唱、混搭等 — 统一的音乐生成端点
`/generate` 端点支持 **15 种不同的任务类型**，每种类型需要不同的参数集。在调用此端点之前，我们**强烈建议**使用 [Generate Schema](/zh/api-reference/suno/generateSchema) 端点获取您任务类型所需的精确必填/可选字段和完整请求示例。
## 快速开始
调用 `GET /suno/v2/generate/schema?task=create` 获取 `create` 任务的参数模式和请求示例。
参见 [Generate Schema →](/zh/api-reference/suno/generateSchema)
使用正确的参数调用 `POST /suno/v2/generate`。
使用返回的 `taskId` 轮询[获取任务状态](/zh/api-reference/suno/task)，直到状态为 `success`。
## 任务类型概览
| 任务 | 描述 | 关键必填字段 |
| ------------------- | --------------- | ------------------------------------------------------------------------------- |
| `create` | 从零开始创建新音乐 | `model` |
| `extend` | 延伸已有音乐 | `clip_id`, `model` |
| `upload_extend` | 延伸已上传的音频 | `audio_url`, `model` |
| `upload_cover` | 翻唱已上传的音频 | `audio_url`, `model` |
| `cover` | 翻唱已有片段 | `clip_id`, `model` |
| `use_styles_lyrics` | 使用片段的风格搭配新歌词 | `clip_id`, `model` |
| `replace_section` | 替换已有音频的某个段落 | `clip_id`, `range`, `infill_context_range`, `continued_aligned_prompt`, `model` |
| `add_instrumental` | 为指定范围添加伴奏 | `clip_id`, `range`, `model` |
| `add_vocals` | 为指定范围添加人声 | `clip_id`, `range`, `model` |
| `gen_stem_two` | 生成双轨音轨（人声 + 伴奏） | `clip_id`, `model` |
| `gen_stem_all` | 生成所有音轨 | `clip_id`, `model` |
| `mashup` | 混搭两首歌曲 | `mashup_clip_ids`, `model` |
| `sample` | 从已有片段中采样 | `clip_id`, `range`, `model` |
| `inspiration` | 基于真实播放列表生成 | `playlist_id`, `model` — 见 [Inspiration 指南](/zh/api-reference/suno/inspiration) |
| `sound` | 生成音效 | `sound`, `model` |
所有任务都需要 `task` 和 `model` 字段。使用 `GET /suno/v2/generate/schema?task=xxx` 获取任何特定任务类型的完整参数详情。
## 通用参数
以下参数在大多数任务类型中通用：
| 参数 | 类型 | 描述 |
| ------------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| `task` | string | **必填**。任务类型（见上表） |
| `model` | string | **必填**。模型版本：`chirp-v55`、`chirp-v50`、`chirp-45+`、`chirp-v45`、`chirp-v45-lite`、`chirp-v40`、`chirp-v35` |
| `prompt` | string | 歌词或提示文本 |
| `tags` | string \| string\[] | 风格标签（例如 `"Pop, Happy, Upbeat"`） |
| `negative_tags` | string \| string\[] | 要排除的风格 |
| `title` | string | 歌曲标题 |
| `make_instrumental` | boolean | 生成无人声版本（默认：`false`） |
| `vocal_gender` | string | `"m"`（男声）或 `"f"`（女声） |
| `controls` | object | 高级控制：`style_weight`、`audio_weight`、`weirdness_constraint`（0\~1） |
| `persona` | object | 用于风格模仿的声音角色 |
## 示例
```bash Create Music theme={null}
curl -X POST https://api.mountsea.ai/suno/v2/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{
"task": "create",
"model": "chirp-v55",
"prompt": "[Verse]\nHello world, here I come...\n\n[Chorus]\nLa la la...",
"tags": "Pop, Happy, Upbeat",
"title": "Summer Vibes"
}'
```
```bash Extend Music theme={null}
curl -X POST https://api.mountsea.ai/suno/v2/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{
"task": "extend",
"model": "chirp-v55",
"clip_id": "clip_abc123",
"continue_at": 30,
"tags": "Pop, Happy"
}'
```
```bash Generate Sound Effect theme={null}
curl -X POST https://api.mountsea.ai/suno/v2/generate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-key" \
-d '{
"task": "sound",
"model": "chirp-v55",
"sound": {
"description": "A deep bass drop with warm analog texture",
"type": "one_shot",
"key": "F#",
"bpm": 120
}
}'
```
**`task=inspiration`** 必须使用 [创建播放列表](/zh/api-reference/suno/playlistCreate) 返回的真实 `playlist_id`。旧模式 `playlist_id: "inspiration"` + `playlist_clip_ids` 已**废弃**。详见 [Inspiration 流程](/zh/api-reference/suno/inspiration)。
**不确定该传哪些参数？** 调用 `GET /suno/v2/generate/schema?task=your_task` — 它会返回每种任务类型的必填字段、可选字段、不允许的字段和完整的请求示例。
[试用 Generate Schema →](/zh/api-reference/suno/generateSchema)
## OpenAPI
````yaml POST /suno/v2/generate
openapi: 3.0.0
info:
title: Suno AI
description: API documentation for Suno AI
version: 1.0.0
contact: {}
servers:
- url: https://api.mountsea.ai
description: API Gateway
security: []
tags:
- name: suno
description: ''
paths:
/suno/v2/generate:
post:
tags:
- suno
description: generate or extend music
operationId: ApiPublicController_generate
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateMusicDto'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TaskIdDto'
security:
- bearerAuth: []
components:
schemas:
GenerateMusicDto:
type: object
properties:
task:
enum:
- create
- extend
- upload_extend
- upload_cover
- cover
- use_styles_lyrics
- replace_section
- add_instrumental
- add_vocals
- gen_stem_two
- gen_stem_all
- mashup
- sample
- inspiration
- sound
type: string
description: >-
Task type. Use GET /generate/schema?task=xxx to query required
fields for each task.
example: create
make_instrumental:
type: boolean
default: false
description: 'Whether to make instrumental (no vocals). [Optional: all tasks]'
example: false
prompt:
type: string
description: >-
Lyrics or prompt text. [Optional: all tasks] For replace_section:
lyrics within infill_context_range (modified if replacement changes
lyrics).
example: |-
[Verse]
Hello world, here I come...
[Chorus]
La la la...
continued_aligned_prompt:
type: string
description: >-
Full song lyrics after replacement. [Required: replace_section]
Contains the complete lyrics of the entire song with the replaced
section updated.
example: |-
[Verse 1]
Original lyrics...
[Chorus]
New replaced lyrics...
[Verse 2]
More lyrics...
infill_lyrics:
type: string
description: >-
Lyrics for the replaced section only. [Optional: replace_section]
The specific lyrics within the range being replaced.
example: |-
[Bridge]
This is the new bridge section
With updated lyrics...
gpt_description_prompt:
type: string
description: >-
Short description for GPT lyrics generation. [Optional: create,
mashup, etc.]
example: A happy pop song about summer vacation
tags:
description: 'Style tags. Supports string or array. [Optional: all tasks]'
oneOf:
- type: string
example: Pop, Happy, Upbeat
- type: array
items:
type: string
example:
- Pop
- Happy
- Upbeat
negative_tags:
description: 'Negative style tags to exclude. [Optional: all tasks]'
oneOf:
- type: string
example: Sad, Slow
- type: array
items:
type: string
example:
- Sad
- Slow
model:
type: string
description: >-
Model version. Supports standard models (e.g. chirp-v50) and custom
models (chirp-custom:).
example: chirp-v50
title:
type: string
description: 'Song title. [Optional: all tasks]'
example: Summer Vibes
clip_id:
type: string
description: >-
Source clip ID. [Required: extend, cover, use_styles_lyrics,
replace_section, add_instrumental, add_vocals, gen_stem_*, sample]
example: clip_abc123
continue_at:
type: number
minimum: 0
description: 'Continue position in seconds. [Optional: extend, upload_extend]'
example: 30
range:
description: >-
Target range { start_s, end_s }. [Required: replace_section, sample]
For replace_section: the section to replace (duration should be > 6
seconds). For sample: the time range to sample from source clip.
example:
start_s: 15.36
end_s: 53.8
allOf:
- $ref: '#/components/schemas/RangeDto'
infill_type:
type: string
enum:
- smart
- classic
- fixed
description: >-
Infill mode for replace_section. [Optional: replace_section] "smart"
= auto-select based on duration (default), "classic" = always use
infill (better for long selections), "fixed" = always use
fixed_infill (better for short selections).
example: smart
infill_context_range:
description: >-
Infill context range (must encompass range). [Required:
replace_section] Should extend ~30s before range.start_s and ~30s
after range.end_s. If range starts within first 30s, use 0 for
start_s. If range ends within last 30s of song, use song duration
for end_s.
example:
start_s: 0
end_s: 69.16
allOf:
- $ref: '#/components/schemas/RangeDto'
persona:
description: >-
Artist persona config for style mimicking. [Optional: create, cover,
extend]
example:
persona_id: persona_xyz789
artist_clip_id: clip_abc123
persona_style: vox
allOf:
- $ref: '#/components/schemas/PersonaDto'
controls:
description: 'Advanced control sliders (0~1). [Optional: all tasks]'
example:
style_weight: 0.6
audio_weight: 0.4
weirdness_constraint: 0.2
allOf:
- $ref: '#/components/schemas/ControlsDto'
vocal_gender:
type: string
enum:
- m
- f
description: 'Vocal gender (m=male, f=female). [Optional: all tasks]'
example: m
audio_url:
type: string
format: uri
description: 'Audio URL for upload tasks. [Required: upload_extend, upload_cover]'
example: https://example.com/audio.mp3
mashup_clip_ids:
description: 'Two clip IDs for mashup [clip_a, clip_b]. [Required: mashup]'
example:
- clip_abc123
- clip_def456
type: array
items:
type: string
playlist_id:
type: string
description: >-
Suno playlist ID. [Required: inspiration] Must be obtained via
/playlist/create → /playlist/addClips before calling /generate. Add
inspiration clips (1–4, same account) to the playlist first. When
combined with persona (vox_playlist_condition), the playlist must
exist on the same account as the persona.
example: 119573ff-8e48-4fe6-9029-39c76c9a5597
sound:
description: >-
Sound generation config. [Required: sound] description is the core
sound prompt (also auto-used as title). type/key/bpm are optional
advanced options. Tags are auto-assembled; user-provided tags are
ignored for sound task.
example:
description: 深沉的低音和温暖的模拟质感
type: one_shot
key: F#
bpm: 2
allOf:
- $ref: '#/components/schemas/SoundDto'
required:
- task
- model
TaskIdDto:
type: object
properties:
taskId:
type: string
description: task id. Use this id to query task status.
example: 15c257ff-43f7-4678-bd41-202ad6b8488b
required:
- taskId
RangeDto:
type: object
properties:
start_s:
type: number
minimum: 0
description: Start time in seconds.
example: 10
end_s:
type: number
minimum: 0
description: End time in seconds. Must be >= start_s.
example: 25
required:
- start_s
- end_s
PersonaDto:
type: object
properties:
artist_clip_id:
type: string
description: Artist clip ID for style reference.
example: clip_abc123
persona_id:
type: string
description: Persona/timbre ID.
example: persona_xyz789
persona_style:
type: string
description: Persona style. Only "vox" supported for chirp-v50+.
example: vox
default: null
enum:
- vox
is_voice:
type: boolean
default: false
description: >-
Whether this is a voice persona (created via
/voicePersona/init+complete with voice recording). Voice personas
are bound to a specific account by voiceprint and MUST be used on
the same account that created them. Regular personas (created via
/persona) are not account-bound and can be used by any account.
Default: false (regular persona).
example: false
required:
- artist_clip_id
- persona_id
ControlsDto:
type: object
properties:
style_weight:
type: number
minimum: 0
maximum: 1
description: Style weight (0~1). Controls how much style influences generation.
example: 0.5
audio_weight:
type: number
minimum: 0
maximum: 1
description: >-
Audio weight (0~1). Controls how much original audio influences
generation.
example: 0.5
weirdness_constraint:
type: number
minimum: 0
maximum: 1
description: >-
Weirdness/creativity constraint (0~1). Higher values produce more
creative results.
example: 0.3
SoundDto:
type: object
properties:
description:
type: string
description: >-
Describe the sound you want. This is the core input for sound
generation. Also used as title (truncated if too long).
example: 一种丰富且沉浸式的音效，具有深沉的低音、温暖的模拟质感和清晰通透的高频。
type:
type: string
enum:
- one_shot
- loop
description: 'Sound type: "one_shot" (default) or "loop".'
example: one_shot
key:
type: string
enum:
- C
- C maj
- C min
- C#
- C# maj
- C# min
- D
- D maj
- D min
- D#
- D# maj
- D# min
- E
- E maj
- E min
- F
- F maj
- F min
- F#
- F# maj
- F# min
- G
- G maj
- G min
- G#
- G# maj
- G# min
- A
- A maj
- A min
- A#
- A# maj
- A# min
- B
- B maj
- B min
description: Musical key. Omit for "Any".
example: A min
bpm:
type: number
minimum: 1
maximum: 300
description: BPM / tempo value (1–300). Omit for "Auto".
example: 2
required:
- description
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````