# 生成 Suno Persona

> 音频生成

基于 Suno 已有音频生成 Persona（音色/风格角色），用于后续音乐生成时复用该音色特征。

**使用流程：**
1. 提交音乐生成任务，获取 taskId
2. 等待音乐生成完成，获取 audioId
3. 调用本接口生成 Persona，获取 personaId
4. 在后续音乐生成时使用 personaId

**cURL 示例：**

```bash
curl --request POST \
  --url "https://api.modelverse.cn/v1/sunoapi/generate-persona" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "taskId": "5c79****be8e",
    "audioId": "e231****-****-****-****-****8cadc7dc",
    "name": "Ethereal Soprano",
    "description": "A hauntingly beautiful female soprano voice with operatic qualities",
    "vocalStart": 10.0,
    "vocalEnd": 30.0,
    "style": "Opera"
  }'
```

## 请求地址

`POST https://api.modelverse.cn/v1/sunoapi/generate-persona`

## 请求体

## 响应

- **200** — Persona 生成成功
- **400** — 参数错误
- **401** — 鉴权失败
- **409** — Persona 已存在
- **502** — 网关错误
- **default** — 错误响应

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Suno 生成Persona 接口文档",
    "version": "1.0.0",
    "description": "基于 Suno 已有音频生成 Persona（音色/风格角色），用于后续音乐生成时复用该音色特征。\n接口路径：`POST /v1/sunoapi/generate-persona`\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 端点"
    }
  ],
  "tags": [
    {
      "name": "Suno Generate Persona",
      "description": "Suno Persona 生成操作"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/sunoapi/generate-persona": {
      "post": {
        "tags": [
          "Suno Generate Persona"
        ],
        "operationId": "generateSunoPersona",
        "summary": "生成 Suno Persona",
        "description": "基于 Suno 已有音频生成 Persona（音色/风格角色），用于后续音乐生成时复用该音色特征。\n\n**使用流程：**\n1. 提交音乐生成任务，获取 taskId\n2. 等待音乐生成完成，获取 audioId\n3. 调用本接口生成 Persona，获取 personaId\n4. 在后续音乐生成时使用 personaId\n\n**cURL 示例：**\n\n```bash\ncurl --request POST \\\n  --url \"https://api.modelverse.cn/v1/sunoapi/generate-persona\" \\\n  --header \"Authorization: Bearer YOUR_API_KEY\" \\\n  --header \"Content-Type: application/json\" \\\n  --data '{\n    \"taskId\": \"5c79****be8e\",\n    \"audioId\": \"e231****-****-****-****-****8cadc7dc\",\n    \"name\": \"Ethereal Soprano\",\n    \"description\": \"A hauntingly beautiful female soprano voice with operatic qualities\",\n    \"vocalStart\": 10.0,\n    \"vocalEnd\": 30.0,\n    \"style\": \"Opera\"\n  }'\n```\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeneratePersonaRequest"
              },
              "examples": {
                "basic": {
                  "summary": "基础请求（必填字段）",
                  "value": {
                    "taskId": "5c79****be8e",
                    "audioId": "e231****-****-****-****-****8cadc7dc",
                    "name": "Ethereal Soprano",
                    "description": "A hauntingly beautiful female soprano voice with operatic qualities"
                  }
                },
                "full": {
                  "summary": "完整参数请求",
                  "value": {
                    "taskId": "5c79****be8e",
                    "audioId": "e231****-****-****-****-****8cadc7dc",
                    "name": "Ethereal Soprano",
                    "description": "A hauntingly beautiful female soprano voice with operatic qualities",
                    "vocalStart": 10,
                    "vocalEnd": 30,
                    "style": "Opera"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Persona 生成成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功响应",
                    "value": {
                      "code": 200,
                      "msg": "success",
                      "data": {
                        "personaId": "abc123-def456-ghi789",
                        "name": "Ethereal Soprano",
                        "description": "A hauntingly beautiful female soprano voice with operatic qualities"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "missingTaskId": {
                    "summary": "缺少 taskId",
                    "value": {
                      "code": 400,
                      "msg": "taskId is required"
                    }
                  },
                  "invalidVocalRange": {
                    "summary": "vocal 时间范围无效",
                    "value": {
                      "code": 400,
                      "msg": "vocal range must be between 10 and 30 seconds"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "未授权",
                    "value": {
                      "code": 401,
                      "msg": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Persona 已存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "alreadyExists": {
                    "summary": "Persona 已存在",
                    "value": {
                      "code": 409,
                      "msg": "Persona already exists for this music",
                      "data": null
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "网关错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "upstreamFailed": {
                    "summary": "上游请求失败",
                    "value": {
                      "code": 502,
                      "msg": "request upstream failed"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "错误响应",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API key，在请求头中以 `Authorization: Bearer <API_KEY>` 格式发送\n"
      }
    },
    "schemas": {
      "GeneratePersonaRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "taskId",
          "audioId",
          "name",
          "description"
        ],
        "properties": {
          "taskId": {
            "type": "string",
            "description": "原始音乐生成任务ID（来自 `/v1/tasks/submit` 的响应）",
            "example": "5c79****be8e"
          },
          "audioId": {
            "type": "string",
            "description": "要创建 Persona 的音频ID（来自任务状态查询中的音频ID）",
            "example": "e231****-****-****-****-****8cadc7dc"
          },
          "name": {
            "type": "string",
            "description": "Persona 名称，用于标识该音色",
            "example": "Ethereal Soprano"
          },
          "description": {
            "type": "string",
            "description": "音乐特征、风格和个性的详细描述",
            "example": "A hauntingly beautiful female soprano voice with operatic qualities"
          },
          "vocalStart": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "description": "分析片段开始时间（秒），默认 0.0",
            "example": 10
          },
          "vocalEnd": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "description": "分析片段结束时间（秒），默认 30.0。vocalEnd - vocalStart 必须在 10-30 秒范围内",
            "example": 30
          },
          "style": {
            "type": "string",
            "description": "音乐风格标签，用于帮助分类 Persona",
            "example": "Opera"
          }
        }
      },
      "GeneratePersonaResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "msg",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "响应状态码，200 表示成功",
            "example": 200
          },
          "msg": {
            "type": "string",
            "description": "状态说明",
            "example": "success"
          },
          "data": {
            "$ref": "#/components/schemas/GeneratePersonaData"
          }
        }
      },
      "GeneratePersonaData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "personaId",
          "name",
          "description"
        ],
        "properties": {
          "personaId": {
            "type": "string",
            "description": "生成的 Persona 唯一标识符，后续音乐生成时可使用",
            "example": "abc123-def456-ghi789"
          },
          "name": {
            "type": "string",
            "description": "请求中提供的 Persona 名称",
            "example": "Ethereal Soprano"
          },
          "description": {
            "type": "string",
            "description": "请求中提供的详细描述",
            "example": "A hauntingly beautiful female soprano voice with operatic qualities"
          }
        }
      },
      "GeneratePersonaErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code",
          "msg"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "错误状态码",
            "example": 400
          },
          "msg": {
            "type": "string",
            "description": "错误信息",
            "example": "taskId is required"
          },
          "data": {
            "type": "object",
            "nullable": true,
            "description": "响应数据（错误时通常为 null）"
          }
        }
      }
    }
  }
}
```