> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunoapi.org/llms.txt
> Use this file to discover all available pages before exploring further.
# 生成 Persona
> 基于已生成的音乐创建个性化的音乐 Persona，为音乐赋予独特的身份和特征。
### 使用指南
* 此接口用于为已生成的音乐创建 Persona（音乐角色）
* 需要提供来自支持的音乐生成相关接口（生成、扩展、混音）的 taskId 和音频ID
* 可以自定义 Persona 的名称和描述，为音乐赋予独特的个性
* 生成的 Persona 可用于后续的音乐创作和风格迁移
* 可选指定 vocalStart 和 vocalEnd 来定义分析片段的时间范围（10-30秒）。如果不提供，默认值为 0.0 和 30.0
### 参数详情
* `taskId`: 必需参数，指定原始音乐生成任务的唯一标识符。可以是以下接口返回的 taskId：
* [生成音乐](./generate-music) (`/api/v1/generate`)
* [扩展音乐](./extend-music) (`/api/v1/generate/extend`)
* `audioId`: 必需参数，指定要创建 Persona 的音频ID
* `name`: 必需参数，为 Persona 指定一个易于识别的名称
* `description`: 必需参数，描述 Persona 的音乐特征、风格和个性
* `vocalStart`: 可选参数，音频分析片段的开始时间（秒）。默认值为 0.0。必须在 0 到音频总时长之间，且片段长度（vocalEnd - vocalStart）必须在 10-30 秒之间。
* `vocalEnd`: 可选参数，音频分析片段的结束时间（秒）。默认值为 30.0。必须在 0 到音频总时长之间，且片段长度（vocalEnd - vocalStart）必须在 10-30 秒之间。
* `style`: 可选参数，音乐风格标签，用于帮助分类 Persona
### 开发者注意事项
* **重要提示**：调用此接口前请确保音乐生成任务已完全完成。如果音乐正在生成中时调用此接口将会返回失败
* **模型要求**：Persona 生成支持使用 V4 及以上版本模型生成的音乐的 taskId
* 建议为 Persona 提供详细的描述，以便更好地捕捉音乐特征
* 返回的 `personaId` 可以用于后续的音乐生成请求中，以创作具有相似风格特征的音乐
* 你可以将 `personaId` 应用到以下接口：
* [生成音乐](./generate-music)
* [扩展音乐](./extend-music)
* [上传并翻唱音频](./upload-and-cover-audio)
* [上传并扩展音频](./upload-and-extend-audio)
* 每个音频ID只能生成一次 Persona
### 参数示例
```json 使用默认值 theme={null}
{
"taskId": "5c79****be8e",
"audioId": "e231****-****-****-****-****8cadc7dc",
"name": "电子流行歌手",
"description": "具有现代电子音乐风格的流行歌手，擅长动感节奏和合成器音色",
"style": "电子流行"
}
```
```json 自定义时间范围 theme={null}
{
"taskId": "5c79****be8e",
"audioId": "e231****-****-****-****-****8cadc7dc",
"name": "电子流行歌手",
"description": "具有现代电子音乐风格的流行歌手，擅长动感节奏和合成器音色",
"vocalStart": 10,
"vocalEnd": 30,
"style": "电子流行"
}
```
确保使用的 taskId 对应的音乐生成任务已完成，且 audioId 有效。
为 Persona 提供详细而具体的描述可以帮助系统更准确地捕捉音乐风格特征。
## OpenAPI
````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/generate-persona
openapi: 3.0.0
info:
title: intro
description: 这是生成音频的API接口文档
version: 1.0.0
contact:
name: 技术支持
email: support@sunoapi.org
servers:
- url: https://api.sunoapi.org
description: API 服务器
security:
- BearerAuth: []
tags:
- name: Music Generation
description: 用于创建和管理音乐生成任务的接口
- name: Lyrics Generation
description: 用于歌词生成和管理的接口
- name: WAV Conversion
description: 用于将音乐转换为WAV格式的接口
- name: Vocal Removal
description: 用于从音乐轨道中移除人声的接口
- name: Music Video Generation
description: 用于生成MP4视频的接口
- name: Account Management
description: 用于账户和积分管理的接口
paths:
/api/v1/generate/generate-persona:
post:
tags:
- 音乐生成
summary: 生成 Persona
operationId: generate-persona
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- taskId
- audioId
- name
- description
properties:
taskId:
type: string
description: |-
原始音乐生成任务的唯一标识符。可以是以下任一接口返回的 taskId：
- 生成音乐 (/api/v1/generate)
- 扩展音乐 (/api/v1/generate/extend)
example: 5c79****be8e
audioId:
type: string
description: 要创建 Persona 的音轨的音频ID。
example: e231****-****-****-****-****8cadc7dc
name:
type: string
description: Persona 的名称。一个能够捕捉音乐风格或角色本质的描述性名称。
example: 电子流行歌手
description:
type: string
description: Persona 的音乐特征、风格和个性的详细描述。请具体说明流派、情绪、乐器使用和人声特质。
example: 具有现代电子音乐风格的流行歌手，擅长动感节奏和合成器音色
vocalStart:
type: number
description: >-
Start time (in seconds) of the audio segment to analyze for
Persona generation. Optional. Default value is 0.0. Must be
between 0 and the audio duration. The segment length
(vocalEnd - vocalStart) must be between 10-30 seconds.
minimum: 0
default: 0
example: 0
vocalEnd:
type: number
description: >-
End time (in seconds) of the audio segment to analyze for
Persona generation. Optional. Default value is 30.0. Must be
between 0 and the audio duration. The segment length
(vocalEnd - vocalStart) must be between 10-30 seconds.
minimum: 0
default: 30
example: 30
style:
type: string
description: Music style label to help categorize the Persona. Optional.
example: Electronic Pop
responses:
'200':
description: 请求成功
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 409
- 422
- 429
- 451
- 455
- 500
description: |-
响应状态码
- **200**: 成功 - 请求已成功处理
- **401**: 未授权 - 身份验证凭据缺失或无效
- **402**: 积分不足 - 账户没有足够的积分执行此操作
- **404**: 未找到 - 请求的资源或端点不存在
- **409**: 冲突 - 该音乐的 Persona 已存在
- **422**: 验证错误 - 请求参数未通过验证检查
- **429**: 超出限制 - 已超过对此资源的请求限制
- **451**: 未授权 - 获取音乐数据失败。请验证您或您的服务提供商设置的任何访问限制。
- **455**: 服务不可用 - 系统当前正在进行维护
- **500**: 服务器错误 - 处理请求时发生意外错误
msg:
type: string
description: 当 code != 200 时的错误信息
example: success
- type: object
properties:
data:
type: object
properties:
personaId:
type: string
description: >-
生成的 Persona 的唯一标识符。该 personaId
可用于后续的音乐生成请求（生成音乐、扩展音乐、上传并翻唱音频、上传并扩展音频），以创作具有相似风格特征的音乐。
example: a1b2****c3d4
name:
type: string
description: 请求中提供的 Persona 名称。
example: 电子流行歌手
description:
type: string
description: 请求中提供的 Persona 的音乐特征、风格和个性的详细描述。
example: 具有现代电子音乐风格的流行歌手，擅长动感节奏和合成器音色
'500':
$ref: '#/components/responses/Error'
components:
responses:
Error:
description: 服务器异常
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: |-
# 🔑 API 认证说明
所有接口都需要通过 Bearer Token 方式进行认证。
## 获取 API Key
1. 访问 [API Key 管理页面](https://sunoapi.org/api-key) 获取您的 API Key
## 使用方式
在请求头中添加：
```
Authorization: Bearer YOUR_API_KEY
```
> **⚠️ 注意：**
> - 请妥善保管您的 API Key，不要泄露给他人
> - 如果怀疑 API Key 泄露，请立即在管理页面重置
````