> ## 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.

# 创建角色

> 从音频片段创建声音角色

基于音频片段创建角色。角色可用于生成具有一致声音特征的音乐。

<Info>
  此端点**直接**返回创建的角色（不是任务 ID）。对于声音角色（`persona_type: "vox"`），请先使用[获取人声音轨](/zh/api-reference/suno/getVoxStem)提取人声音轨。
</Info>

## 请求体

<ParamField body="clip_id" type="string" required>
  用于创建角色的音频片段 ID。
</ParamField>

<ParamField body="name" type="string" required>
  角色名称。
</ParamField>

<ParamField body="is_public" type="boolean" required default={true}>
  角色是否可公开访问。
</ParamField>

<ParamField body="description" type="string">
  角色描述。
</ParamField>

<ParamField body="persona_type" type="string">
  角色类型。声音角色请使用 `"vox"`。
</ParamField>

<ParamField body="vox_audio_id" type="string">
  从[获取人声音轨](/zh/api-reference/suno/getVoxStem)返回的人声音频 ID。声音角色必填。
</ParamField>

<ParamField body="vocal_start_s" type="number">
  要使用的声乐片段开始时间（秒）。
</ParamField>

<ParamField body="vocal_end_s" type="number">
  要使用的声乐片段结束时间（秒）。
</ParamField>

<ParamField body="user_input_styles" type="string">
  描述角色的风格标签（例如 "soulful vocals, R\&B, smooth harmonies"）。
</ParamField>

<ParamField body="image_s3_id" type="string">
  角色头像的 Base64 编码图片（格式：`data:image/png;base64,...`）。
</ParamField>

## 响应

响应包含完整的角色对象及所有详情。

<ResponseField name="id" type="string">
  创建的角色 ID。
</ResponseField>

<ResponseField name="name" type="string">
  角色名称。
</ResponseField>

<ResponseField name="description" type="string">
  角色描述。
</ResponseField>

<ResponseField name="persona_type" type="string">
  角色类型（例如 `"vox"`）。
</ResponseField>

<ResponseField name="is_public" type="boolean">
  角色是否公开。
</ResponseField>

<ResponseField name="clip" type="object">
  源片段信息。
</ResponseField>

<ResponseField name="vocal_start_s" type="number">
  人声开始时间。
</ResponseField>

<ResponseField name="vocal_end_s" type="number">
  人声结束时间。
</ResponseField>

## 示例

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = 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: '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'
    })
  });

  const persona = await response.json();
  console.log('Created Persona ID:', persona.id);
  console.log('Persona Name:', persona.name);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.mountsea.ai/suno/v2/persona',
      headers={
          'Content-Type': 'application/json',
          'Authorization': 'Bearer your-api-key'
      },
      json={
          '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'
      }
  )

  persona = response.json()
  print(f"Created Persona ID: {persona['id']}")
  print(f"Persona Name: {persona['name']}")
  ```
</CodeGroup>

## 响应示例

```json theme={null}
{
  "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
}
```

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

创建声音角色请按以下步骤操作：

```javascript theme={null}
// 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);
```

<Tip>
  创建后，可以通过 [Generate Music](/zh/api-reference/suno/generate) 端点的 `persona` 参数使用角色，以创建具有一致声音特征的音乐。
</Tip>