跳转到主要内容
POST
/
suno
/
v2
/
persona
创建角色
curl --request POST \
  --url https://api.mountsea.ai/suno/v2/persona \
  --header 'Content-Type: application/json' \
  --data '
{
  "clip_id": "<string>",
  "name": "<string>",
  "is_public": true,
  "description": "<string>",
  "persona_type": "<string>",
  "vox_audio_id": "<string>",
  "vocal_start_s": 123,
  "vocal_end_s": 123,
  "user_input_styles": "<string>",
  "image_s3_id": "<string>"
}
'
{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "persona_type": "<string>",
  "is_public": true,
  "clip": {},
  "vocal_start_s": 123,
  "vocal_end_s": 123
}

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.

基于音频片段创建角色。角色可用于生成具有一致声音特征的音乐。
此端点直接返回创建的角色（不是任务 ID）。对于声音角色（persona_type: "vox"），请先使用获取人声音轨提取人声音轨。

​
请求体

​
clip_id
string
必填
用于创建角色的音频片段 ID。
​
name
string
必填
角色名称。
​
is_public
boolean
默认值:true
必填
角色是否可公开访问。
​
description
string
角色描述。
​
persona_type
string
角色类型。声音角色请使用 "vox"。
​
vox_audio_id
string
从获取人声音轨返回的人声音频 ID。声音角色必填。
​
vocal_start_s
number
要使用的声乐片段开始时间（秒）。
​
vocal_end_s
number
要使用的声乐片段结束时间（秒）。
​
user_input_styles
string
描述角色的风格标签（例如 “soulful vocals, R&B, smooth harmonies”）。
​
image_s3_id
string
角色头像的 Base64 编码图片（格式：data:image/png;base64,...）。

​
响应

响应包含完整的角色对象及所有详情。
​
id
string
创建的角色 ID。
​
name
string
角色名称。
​
description
string
角色描述。
​
persona_type
string
角色类型（例如 "vox"）。
​
is_public
boolean
角色是否公开。
​
clip
object
源片段信息。
​
vocal_start_s
number
人声开始时间。
​
vocal_end_s
number
人声结束时间。

​
示例

curl -X POST https://api.mountsea.ai/suno/v2/persona \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "clip_id": "316c630b-284b-4fbd-9b35-f0551d4b98da",
    "name": "My Vocal Persona",
    "description": "A soulful R&B voice",
    "is_public": true,
    "persona_type": "vox",
    "vox_audio_id": "373efa9c-a366-42bb-806c-afdfc9b306a7",
    "vocal_start_s": 16.13,
    "vocal_end_s": 46.13,
    "user_input_styles": "soulful vocals, R&B, smooth harmonies"
  }'

​
响应示例

{
  "id": "61515b86-62f5-427a-bc29-6befa382536a",
  "name": "My Vocal Persona",
  "description": "A soulful R&B voice",
  "image_s3_id": "https://cdn2.suno.ai/image_316c630b-284b-4fbd-9b35-f0551d4b98da.jpeg",
  "root_clip_id": "316c630b-284b-4fbd-9b35-f0551d4b98da",
  "clip": {
    "id": "316c630b-284b-4fbd-9b35-f0551d4b98da",
    "status": "complete",
    "title": "Roadtrip Sunrise",
    "audio_url": "https://cdn1.suno.ai/316c630b-284b-4fbd-9b35-f0551d4b98da.mp3",
    "image_url": "https://cdn2.suno.ai/image_316c630b-284b-4fbd-9b35-f0551d4b98da.jpeg"
  },
  "persona_type": "vox",
  "is_public": true,
  "user_input_styles": "soulful vocals, R&B, smooth harmonies",
  "vocal_start_s": 16.13,
  "vocal_end_s": 46.13,
  "vocal_clip_id": "70149747-3f33-4e56-a4f4-8c44c30d7a0f",
  "upvote_count": 0,
  "clip_count": 1,
  "follower_count": 0
}

​
工作流程：创建声音角色

创建声音角色请按以下步骤操作： 
// Step 1: Get vox stem to extract vocals
const voxResponse = await fetch('https://api.mountsea.ai/suno/v2/getVoxStem', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-api-key'
  },
  body: JSON.stringify({ clip_id: 'your-clip-id' })
});
const voxData = await voxResponse.json();
// voxData.id is the vox_audio_id to use

// Step 2: Create persona with the extracted vox audio
const personaResponse = await fetch('https://api.mountsea.ai/suno/v2/persona', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-api-key'
  },
  body: JSON.stringify({
    clip_id: 'your-clip-id',
    name: 'My Vocal Persona',
    is_public: true,
    persona_type: 'vox',
    vox_audio_id: voxData.id,
    vocal_start_s: voxData.vocal_start_s,
    vocal_end_s: voxData.vocal_end_s,
    user_input_styles: 'your style description'
  })
});
const persona = await personaResponse.json();
console.log('Persona created:', persona.id);
创建后，可以通过 Generate Music 端点的 persona 参数使用角色，以创建具有一致声音特征的音乐。