> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno API：人物（Persona）生成

> 基于已有 Suno 音乐作品生成一个音乐人物（Persona）。

## API 接口地址

```
POST https://api.crun.ai/api/v1/client/job/suno-persona-generate
```

<Info>
  该接口在完成校验后会同步返回 persona\_id。\
  生成后的 `persona_id` 可用于音乐生成、扩展、上传扩展以及翻唱等接口。
</Info>

***

## 请求示例

<CodeGroup>
  ```json persona generate theme={null} theme={null}
  {
      "task_id": "task_12345678",
      "suno_id": "suno_abc123",
      "name": "霓虹女妖",
      "description": "一位烟熏感的深夜 R&B 女声歌手，音色轻柔空灵，高音细腻且富有亲密感。",
      "vocal_start": 12.5,
      "vocal_end": 64.0,
      "style": "西方 R&B，氛围感，情绪化，私密感"
  }
  ```
</CodeGroup>

***

## 响应示例

```json success theme={null}
{
    "code": 200,
    "message": "success",
    "data": {
        "persona_id": "persona_123456"
    }
}
```

```json error theme={null}
{
    "code": 422,
    "message": "task_id 不存在",
    "data": null
}
```

***

## 相关资源

<CardGroup cols={2}>
  <Card title="生成音乐" icon="music" href="/zh/suno-api/generate-music">
    通过文本提示创建多种风格的歌曲。
  </Card>

  <Card title="扩展音乐" icon="forward" href="/zh/suno-api/extend-music">
    无缝续写并扩展已有音乐。
  </Card>

  <Card title="上传扩展" icon="upload" href="/zh/suno-api/extend-music-upload">
    上传音频并对作品进行扩展与优化。
  </Card>

  <Card title="音乐翻唱" icon="retweet" href="/zh/suno-api/cover-music">
    用新的风格或声音重新演绎歌曲。
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/suno-api/suno-persona-generate.json post /api/v1/client/job/suno-persona-generate
openapi: 3.0.0
info:
  title: Suno 人物生成 API
  description: 基于已有 Suno 音乐任务生成 Suno 人物（Persona）。
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API 服务地址
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/suno-persona-generate:
    post:
      summary: 生成 Suno 人物
      operationId: suno-persona-generate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - task_id
                - suno_id
                - name
                - description
              properties:
                task_id:
                  type: string
                  description: 音乐任务 ID
                  example: task_12345678
                suno_id:
                  type: string
                  description: Suno 歌曲 ID
                  example: suno_abc123
                name:
                  type: string
                  maxLength: 100
                  description: 人物名称
                  example: 霓虹女妖
                description:
                  type: string
                  maxLength: 1000
                  description: 人物描述
                  example: 一位烟熏感的深夜 R&B 女声，音色空灵且温暖，带有亲密感。
                vocal_start:
                  type: number
                  minimum: 0
                  description: 人声开始时间（秒）
                  example: 12.5
                vocal_end:
                  type: number
                  minimum: 0
                  description: 人声结束时间（秒）
                  example: 64
                style:
                  type: string
                  maxLength: 1000
                  description: 风格描述
                  example: 西方 R&B，情绪化，私密感
            example:
              task_id: task_12345678
              suno_id: suno_abc123
              name: 霓虹女妖
              description: 一位烟熏感的深夜 R&B 女声，音色空灵且温暖，带有亲密感。
              vocal_start: 12.5
              vocal_end: 64
              style: 西方 R&B，情绪化，私密感
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          persona_id:
                            type: string
                            description: 生成的人物 ID
                            example: persona_123456
              example:
                code: 200
                message: success
                data:
                  persona_id: persona_123456
        '422':
          description: 参数校验失败
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
              example:
                code: 422
                message: task_id not found
                data: null
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 401
            - 402
            - 404
            - 422
            - 429
            - 455
            - 500
            - 501
            - 505
          description: |-
            响应状态码

            - **200**：成功
            - **401**：未授权
            - **402**：Credits 不足
            - **404**：资源不存在
            - **422**：参数校验失败
            - **429**：请求过于频繁
            - **455**：服务维护中
            - **500**：服务器错误
            - **501**：生成失败
            - **505**：功能未启用
        message:
          type: string
          description: 响应消息
          example: success
        data:
          nullable: true
      required:
        - code
        - message
  responses:
    Error:
      description: 服务器错误
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |-
        所有 API 均需通过 API Key 进行身份认证。

        获取 API Key：
        1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取 API Key

        使用方式：
        在请求头中添加：

        x-api-key: YOUR_API_KEY

        注意：
        - 请妥善保管 API Key，避免泄露
        - 如怀疑泄露请立即重置

````