> ## Documentation Index > Fetch the complete documentation index at: https://docs.evolink.ai/llms.txt > Use this file to discover all available pages before exploring further. # Suno 音乐生成 Beta > - Suno AI 音乐生成模型，支持根据文本描述或歌词生成完整的音乐作品 - 支持自定义模式（精细控制风格、标题、歌词）和简单模式（AI自动生成） - 支持 [Persona](/cn/api-manual/audio-series/suno/suno-persona-creation) 功能，可复用已创建的声乐/风格特征 - 异步处理模式，使用返回的任务ID [进行查询](/cn/api-manual/task-management/get-task-detail) - 生成的音频链接，有效期为72小时，请尽快保存 - 每次请求会生成多个音乐变体 ## OpenAPI ````yaml cn/api-manual/audio-series/suno/suno-music-generation.json POST /v1/audios/generations openapi: 3.1.0 info: title: Suno音乐生成接口 description: 使用Suno AI模型生成音乐，支持带歌词或纯音乐模式 license: name: MIT version: 1.0.0 servers: - url: https://api.evolink.ai description: 生产环境 security: - bearerAuth: [] paths: /v1/audios/generations: post: tags: - 音频生成 summary: Suno音乐生成接口 description: >- - Suno AI 音乐生成模型，支持根据文本描述或歌词生成完整的音乐作品 - 支持自定义模式（精细控制风格、标题、歌词）和简单模式（AI自动生成） - 支持 [Persona](/cn/api-manual/audio-series/suno/suno-persona-creation) 功能，可复用已创建的声乐/风格特征 - 异步处理模式，使用返回的任务ID [进行查询](/cn/api-manual/task-management/get-task-detail) - 生成的音频链接，有效期为72小时，请尽快保存 - 每次请求会生成多个音乐变体 operationId: createSunoMusicGeneration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SunoMusicGenerationRequest' examples: simple_mode: summary: 简单模式（推荐新手） value: model: suno-v5-beta prompt: 一首欢快的夏日流行歌曲，关于公路旅行和自由 custom_mode_with_lyrics: summary: 自定义模式（带歌词） value: model: suno-v5-beta custom_mode: true instrumental: false style: pop, electronic, upbeat, female vocals, 120bpm title: 夏日梦想 prompt: |- [Verse 1] 驾车行驶在高速路上，车窗敞开 阳光照耀着这座小镇 收音机播放着我们最爱的歌 一切都那么美好 [Chorus] 夏日的梦，夏日的夜 追逐星光和城市灯火 有你在身边 我感到如此快乐 negative_tags: heavy metal, screaming, sad vocal_gender: f custom_mode_with_persona: summary: 自定义模式（使用 Persona） value: model: suno-v5-beta custom_mode: true instrumental: false style: electronic pop, synth wave, 128bpm title: 霓虹梦想家 prompt: |- [Verse] 霓虹灯下漫步街头 城市的脉搏在心中跳动 [Chorus] 我们是追梦者 在星空下起舞 persona_id: 5c57d49ef834110496fae5aa14fec441 persona_model: voice_persona instrumental_mode: summary: 纯音乐模式 value: model: suno-v4.5plus-beta custom_mode: true instrumental: true style: lo-fi, chill, ambient, piano, soft drums title: 雨后午后 responses: '200': description: 音乐任务创建成功 content: application/json: schema: $ref: '#/components/schemas/AudioGenerationResponse' '400': description: 请求参数错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: Invalid request parameters type: invalid_request_error '401': description: 未认证、Token无效或过期 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Invalid or expired token type: authentication_error '402': description: 配额不足、需要充值 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_quota message: Insufficient quota. Please top up your account. type: insufficient_quota '403': description: 无权限访问 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: model_access_denied message: 'Token does not have access to model: suno-v5-beta' type: invalid_request_error '429': description: 请求频率超限 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Too many requests, please try again later type: rate_limit_error '500': description: 服务器内部错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: Internal server error type: api_error '503': description: 服务暂时不可用 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: service_unavailable message: No available channel for the requested model type: api_error components: schemas: SunoMusicGenerationRequest: type: object required: - model - custom_mode - instrumental properties: model: type: string description: >- 模型名称 **向后兼容：** 之前接入的模型名（如 `suno-v5`、`suno-v4.5`、`suno-v4.5plus`、`suno-v4.5all`、`suno-v4`）仍然可用，会自动映射到对应的 `-beta` 版本 **可选值：** - `suno-v5-beta`: V5最新版本（默认推荐），支持 Voice Persona，更卓越的音乐表现力，生成速度更快，prompt最多`5000`字符，style最多`1000`字符 - `suno-v4.5plus-beta`: V4.5+增强版，音色更丰富，新的创作方式，最长8分钟，prompt最多`5000`字符，style最多`1000`字符 - `suno-v4.5all-beta`: V4.5全功能版，更智能的提示词，更快的生成速度，最长8分钟，prompt最多`5000`字符，style最多`1000`字符 - `suno-v4.5-beta`: V4.5版本，更智能的提示词，更快的生成速度，最长8分钟，prompt最多`5000`字符，style最多`1000`字符 - `suno-v4-beta`: V4版本，改进的人声质量，最长4分钟，prompt最多`3000`字符，style最多`200`字符 enum: - suno-v5-beta - suno-v4.5plus-beta - suno-v4.5all-beta - suno-v4.5-beta - suno-v4-beta example: suno-v5-beta custom_mode: type: boolean description: |- 是否开启自定义模式 **说明：** - `false`：简单模式，只需提供`prompt`，AI自动生成歌词和风格 - `true`：自定义模式，可精细控制`style`、`title`、歌词等 **自定义模式下的必填参数：** - `style`: 必填 - `title`: 必填 - `prompt`: 当`instrumental=false`时必填（作为歌词） example: false instrumental: type: boolean description: |- 是否生成纯音乐（无人声） **说明：** - `false`：生成带人声的音乐 - `true`：生成无人声的纯音乐/背景音乐 **注意：** - 在非自定义模式下，此参数对必填字段无影响 - 在自定义模式下，设为`true`时`prompt`变为可选 example: false prompt: type: string description: |- 提示词，描述所需音乐内容 **非自定义模式（`custom_mode=false`）：** - 必填，作为音乐描述，AI自动生成歌词和风格 - 最大长度：`500`字符 **自定义模式（`custom_mode=true`）：** - 当`instrumental=false`时必填，作为精确歌词使用 - 当`instrumental=true`时可选 - 最大长度：V4为`3000`字符，V4.5+为`5000`字符 **歌词格式建议：** - 使用`[Verse]`、`[Chorus]`、`[Bridge]`等标签组织歌词结构 example: 一首欢快的夏日流行歌曲，关于公路旅行和自由 style: type: string description: >- 音乐风格规范 **说明：** - 在自定义模式（`custom_mode=true`）下必填 - 定义音乐的流派、情绪或艺术方向 - 建议使用英文逗号分隔的标签形式 **字符限制：** - V4：最多`200`字符 - V4.5+：最多`1000`字符 **常见风格标签：** - 流派：pop, rock, jazz, classical, electronic, hip-hop, r&b, country, folk - 情绪：happy, sad, energetic, calm, romantic, dark, uplifting - 乐器：piano, guitar, drums, bass, violin, saxophone, synthesizer - 人声：male vocals, female vocals, choir, harmonies - 节奏：slow, fast, upbeat, groovy, 120bpm example: pop, electronic, upbeat, female vocals title: type: string description: |- 歌曲标题 **说明：** - 在自定义模式（`custom_mode=true`）下必填 - 将显示在播放器界面和文件名中 - 最大长度：`80`字符 maxLength: 80 example: 夏日梦想 negative_tags: type: string description: |- 排除风格，指定不希望出现的音乐风格或特征 **示例：** - `heavy metal, screaming, sad` - `rap, fast tempo` example: heavy metal, screaming vocal_gender: type: string description: |- 人声性别偏好 **可选值：** - `m`: 男声 - `f`: 女声 **注意：** - 仅在`custom_mode=true`时生效 - 此参数只能加强概率，不能保证一定遵循指定性别 enum: - m - f example: f style_weight: type: number description: |- 风格权重，控制对指定风格的遵循强度 **取值范围：** `0.0` ~ `1.0`，保留一位小数 **说明：** - 值越高，生成结果越接近指定风格 - 值为`0`时视为未设置 minimum: 0 maximum: 1 example: 0.7 weirdness_constraint: type: number description: |- 怪异度约束，控制生成结果的创意/实验性程度 **取值范围：** `0.0` ~ `1.0`，保留一位小数 **说明：** - 值越高，生成结果越具有创意和实验性 - 值越低，生成结果越传统和保守 - 值为`0`时视为未设置 minimum: 0 maximum: 1 example: 0.3 audio_weight: type: number description: |- 音频权重，控制音频特征的权重 **取值范围：** `0.0` ~ `1.0`，保留一位小数 **说明：** - 值为`0`时视为未设置 minimum: 0 maximum: 1 example: 0.5 persona_id: type: string description: >- Persona ID，应用已创建的 Persona 风格到本次音乐生成 仅在 `custom_mode=true` 时可用。通过 [Suno Persona 创建](/cn/api-manual/audio-series/suno/suno-persona-creation) 接口获得，应用后可保持一致的声乐和风格特征 **获取方式：** 创建 Persona 任务完成后，从 `result_data.persona_id` 中获取 example: 5c57d49ef834110496fae5aa14fec441 persona_model: type: string description: >- Persona 应用方式 **可选值：** 1. `style_persona`: 风格导向型，偏重音乐风格特征（编曲、节奏、音色），支持所有模型版本 2. `voice_persona`: 声音导向型，偏重声乐特征（音色、唱法、声线），**仅 V5 支持** 仅在 `custom_mode=true` 时可用，通常与 `persona_id` 搭配使用。使用 `voice_persona` 时模型必须为 `suno-v5-beta`，否则返回错误 enum: - style_persona - voice_persona example: style_persona callback_url: type: string description: |- 任务完成后的HTTPS回调地址 **回调时机：** - 回调过程分三个阶段：`text`（文本生成）、`first`（第一首完成）、`complete`（全部完成） - 某些情况下可能跳过`text`和`first`阶段，直接返回`complete` **安全限制：** - 仅支持HTTPS协议 - 禁止回调到内网IP地址 - URL长度不超过`2048`字符 **回调机制：** - 超时时间：`10`秒 - 失败后最多重试`3`次 - 回调地址返回2xx状态码视为成功 format: uri example: https://your-domain.com/webhooks/suno-callback AudioGenerationResponse: type: object properties: created: type: integer description: 任务创建时间戳 example: 1766319090 id: type: string description: 任务ID，用于查询任务状态和结果 example: task-unified-1766319089-oqs9cue4 model: type: string description: 实际使用的模型名称 example: suno-v5-beta object: type: string enum: - audio.generation.task description: 任务的具体类型 progress: type: integer description: 任务进度百分比 (0-100) minimum: 0 maximum: 100 example: 0 status: type: string description: 任务状态 enum: - pending - processing - completed - failed example: pending task_info: $ref: '#/components/schemas/AudioTaskInfo' description: 任务详细信息 type: type: string enum: - audio description: 任务的输出类型 example: audio usage: $ref: '#/components/schemas/Usage' description: 使用量和计费信息 ErrorResponse: type: object properties: error: type: object properties: code: type: string description: 错误代码标识符 message: type: string description: 错误描述信息 type: type: string description: 错误类型 AudioTaskInfo: type: object properties: can_cancel: type: boolean description: 任务是否可以取消 example: true estimated_time: type: integer description: 预估完成时间（秒） example: 120 Usage: type: object description: 使用量和计费信息 properties: billing_rule: type: string description: 计费规则 enum: - per_call - per_token - per_second example: per_call credits_reserved: type: number description: 预估消耗积分数 minimum: 0 example: 10 user_group: type: string description: 用户所属计费分组 example: default securitySchemes: bearerAuth: type: http scheme: bearer description: |- ##所有接口均需要使用Bearer Token进行认证## **获取 API Key ：** 访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取您的 API Key **使用时在请求头中添加：** ``` Authorization: Bearer YOUR_API_KEY ``` ````