# Generate Suno Persona

> Audio Generation

Generate a Persona (voice/style character) from existing Suno audio for reuse in subsequent music generation.

**Usage Workflow:**
1. Submit a music generation task to get taskId
2. Wait for music generation to complete and get audioId
3. Call this endpoint to generate Persona and get personaId
4. Use personaId in subsequent music generation

**cURL Example:**

```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"
  }'
```

## Endpoint

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

## Request Body

## Responses

- **200** — Persona generated successfully
- **400** — Parameter error
- **401** — Authentication failed
- **409** — Persona already exists
- **502** — Gateway error
- **default** — Error response

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Suno Generate Persona API",
    "version": "1.0.0",
    "description": "Generate a Persona (voice/style character) from existing Suno audio for reuse in subsequent music generation.\nEndpoint: `POST /v1/sunoapi/generate-persona`\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint"
    }
  ],
  "tags": [
    {
      "name": "Suno Generate Persona",
      "description": "Suno Persona generation operations"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/sunoapi/generate-persona": {
      "post": {
        "tags": [
          "Suno Generate Persona"
        ],
        "operationId": "generateSunoPersona",
        "summary": "Generate Suno Persona",
        "description": "Generate a Persona (voice/style character) from existing Suno audio for reuse in subsequent music generation.\n\n**Usage Workflow:**\n1. Submit a music generation task to get taskId\n2. Wait for music generation to complete and get audioId\n3. Call this endpoint to generate Persona and get personaId\n4. Use personaId in subsequent music generation\n\n**cURL Example:**\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": "Basic request (required fields only)",
                  "value": {
                    "taskId": "5c79****be8e",
                    "audioId": "e231****-****-****-****-****8cadc7dc",
                    "name": "Ethereal Soprano",
                    "description": "A hauntingly beautiful female soprano voice with operatic qualities"
                  }
                },
                "full": {
                  "summary": "Full parameter request",
                  "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 generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Success response",
                    "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": "Parameter error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "missingTaskId": {
                    "summary": "Missing taskId",
                    "value": {
                      "code": 400,
                      "msg": "taskId is required"
                    }
                  },
                  "invalidVocalRange": {
                    "summary": "Invalid vocal range",
                    "value": {
                      "code": 400,
                      "msg": "vocal range must be between 10 and 30 seconds"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "unauthorized": {
                    "summary": "Unauthorized",
                    "value": {
                      "code": 401,
                      "msg": "Unauthorized"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Persona already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "alreadyExists": {
                    "summary": "Persona already exists",
                    "value": {
                      "code": 409,
                      "msg": "Persona already exists for this music",
                      "data": null
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Gateway error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                },
                "examples": {
                  "upstreamFailed": {
                    "summary": "Upstream request failed",
                    "value": {
                      "code": 502,
                      "msg": "request upstream failed"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratePersonaErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API key sent in the `Authorization: Bearer <API_KEY>` header\n"
      }
    },
    "schemas": {
      "GeneratePersonaRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "taskId",
          "audioId",
          "name",
          "description"
        ],
        "properties": {
          "taskId": {
            "type": "string",
            "description": "Original music generation task ID (from `/v1/tasks/submit` response)",
            "example": "5c79****be8e"
          },
          "audioId": {
            "type": "string",
            "description": "Audio ID to create Persona from (from task status query)",
            "example": "e231****-****-****-****-****8cadc7dc"
          },
          "name": {
            "type": "string",
            "description": "Persona name for identifying this voice",
            "example": "Ethereal Soprano"
          },
          "description": {
            "type": "string",
            "description": "Detailed description of musical characteristics, style, and personality",
            "example": "A hauntingly beautiful female soprano voice with operatic qualities"
          },
          "vocalStart": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "description": "Analysis segment start time in seconds, default 0.0",
            "example": 10
          },
          "vocalEnd": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "description": "Analysis segment end time in seconds, default 30.0. vocalEnd - vocalStart must be within 10-30 seconds",
            "example": 30
          },
          "style": {
            "type": "string",
            "description": "Music style tag for categorizing the Persona",
            "example": "Opera"
          }
        }
      },
      "GeneratePersonaResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "msg",
          "data"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "Response status code, 200 indicates success",
            "example": 200
          },
          "msg": {
            "type": "string",
            "description": "Status message",
            "example": "success"
          },
          "data": {
            "$ref": "#/components/schemas/GeneratePersonaData"
          }
        }
      },
      "GeneratePersonaData": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "personaId",
          "name",
          "description"
        ],
        "properties": {
          "personaId": {
            "type": "string",
            "description": "Generated Persona unique identifier for use in subsequent music generation",
            "example": "abc123-def456-ghi789"
          },
          "name": {
            "type": "string",
            "description": "Persona name provided in the request",
            "example": "Ethereal Soprano"
          },
          "description": {
            "type": "string",
            "description": "Detailed description provided in the request",
            "example": "A hauntingly beautiful female soprano voice with operatic qualities"
          }
        }
      },
      "GeneratePersonaErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code",
          "msg"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "description": "Error status code",
            "example": 400
          },
          "msg": {
            "type": "string",
            "description": "Error message",
            "example": "taskId is required"
          },
          "data": {
            "type": "object",
            "nullable": true,
            "description": "Response data (usually null on error)"
          }
        }
      }
    }
  }
}
```