Generate Persona

This page is generated from the upstream official OpenAPI documentation. Endpoints, parameters and examples match the official docs; brand and API domain are replaced with ModelFold.

Endpoint

POST /jobs/createTask

Full URL: https://ai.modelfold.online/v1/jobs/createTask

Authentication: every request must include the Authorization: Bearer <API_KEY> header.

Document updated

If you have already completed the integration process previously, you can still access the old version document at: Old version address (https://ai.modelfold.online/docs/en/suno-api/generate-persona)

Create a personalized music Persona based on generated music, giving the music a unique identity and characteristics.

Usage Guide

Use this endpoint to create Personas (music characters) for generated music:

• Requires the task_id from music generation related endpoints (generate, extend) and audio ID
• Customize the Persona name and description to give music unique personality
• Generated Personas can be used for subsequent music creation and style transfer

Parameter Details

• task_id (Required): Can be obtained from the following endpoints:
  • Generate Music
  • Extend Music
• audio_id (Required): Specifies the audio ID to create Persona for
• name (Required): Assigns an easily recognizable name to the Persona
• description (Required): Describes the Persona's musical characteristics, style, and personality

Developer Notes

:::caution Important Requirements

• Ensure the music generation task is fully completed before calling this endpoint. If the music is still generating, this endpoint will return a failure.

• Each audio ID can only generate a Persona once. :::

• It is recommended to provide detailed descriptions for Personas to better capture musical characteristics.

• The returned persona_id can be used in subsequent music generation requests to create music with similar style characteristics.

• You can apply the persona_id to the following endpoints:

  • Generate Music
  • Extend Music

Parameter Example

{
  "task_id": "5c79****be8e",
  "audio_id": "e231****-****-****-****-****8cadc7dc",
  "name": "Electronic Pop Singer",
  "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones"
}

::: note Ensure that the music generation task corresponding to the task_id is complete and the audio_id is within the valid range. :::

TIP

Providing detailed and specific descriptions for Personas helps the system more accurately capture musical style characteristics.

Request Parameters

Body (application/json)

Parameter	Type	Required	Description
model	string	Yes	The model name to use for generation. Required field. 示例：ai-music-api/generate-persona。
callBackUrl	string	No	The URL to receive generation task completion updates. Optional but recommended for production use. - System will POST task status and results to this URL when generation completes - Callback includes generated content URLs and task information - Your callback endpoint should accept POST requests with JSON payload containing results - Alternatively, poll GET /api/v1/jobs/recordInfo?taskId=... (see Get Task Details). - To ensure callback security, see Webhook Verification Guide for signature verification implementation
input	object	Yes	Input parameters for the generation task
input.task_id	string	Yes	Unique identifier of the original music generation task. Generated by model ai-music-api/generate or ai-music-api/extend. 示例：5c79****be8e。
input.audio_id	string	Yes	Unique identifier of the audio track to create Persona for. This ID is returned in the callBackUrl data after music generation completes. 示例：e231****-****-****-****-****8cadc7dc。
input.name	string	Yes	Name for the Persona. A descriptive name that captures the essence of the musical style or character. 示例：Electronic Pop Singer。
input.description	string	Yes	Detailed description of the Persona's musical characteristics, style, and personality. Be specific about genre, mood, instrumentation, and vocal qualities. 示例：A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones。
input.vocal_start	number	No	Start time (in seconds) for Persona analysis segment extraction. Used to specify the time point in the audio from which to extract the segment for Persona analysis. Must be less than vocal_end, and vocal_end - vocal_start must be between 10–30 seconds. Defaults to 0.0. Default：0。 示例：12.5。
input.vocal_end	number	No	End time (in seconds) for Persona analysis segment extraction. Together with vocal_start, used to specify the time range for analysis. vocal_end - vocal_start must be between 10–30 seconds. Defaults to 30.0. Default：30。 示例：25.8。
input.style	string	No	Optional. Used to supplement the description of the music style tag corresponding to the Persona, such as "Electronic Pop", "Jazz Trio", etc.

Request Example

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ai-music-api/generate-persona",
  "callBackUrl": "https://api.example.com/callback",
  "input": {
    "task_id": "5c79****be8e",
    "audio_id": "e231****-****-****-****-****8cadc7dc",
    "name": "Electronic Pop Singer",
    "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones",
    "vocal_start": 0,
    "vocal_end": 30,
    "style": "Electronic Pop"
  }
}'

{
  "model": "ai-music-api/generate-persona",
  "callBackUrl": "https://api.example.com/callback",
  "input": {
    "task_id": "5c79****be8e",
    "audio_id": "e231****-****-****-****-****8cadc7dc",
    "name": "Electronic Pop Singer",
    "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones",
    "vocal_start": 0,
    "vocal_end": 30,
    "style": "Electronic Pop"
  }
}

Response

200 — Request successful

参数	类型	必填	说明
code	integer	否	Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying). 可选值：200 / 401 / 402 / 404 / 409 / 422 / 429 / 451 / 455 / 500。 示例：200。
msg	string	否	Error message when code != 200 示例：success。
data	object	否	—
data.persona_id	string	否	Unique identifier for the generated Persona. This persona_id can be used in subsequent music generation requests (Generate Music, Extend Music, Upload And Cover Audio, Upload And Extend Audio) to create music with similar style characteristics. 示例：a1b2****c3d4。
data.name	string	否	Name of the Persona as provided in the request. 示例：Electronic Pop Singer。
data.description	string	否	Description of the Persona's musical characteristics, style, and personality as provided in the request. 示例：A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones。

{
  "code": 200,
  "msg": "success",
  "data": {
    "persona_id": "a1b2****c3d4",
    "name": "Electronic Pop Singer",
    "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones"
  }
}

500 — Server error.

参数	类型	必填	说明
code	integer	是	Response status code - 200: Success - Request has been processed successfully - 401: Unauthorized - Authentication credentials are missing or invalid - 402: Insufficient Credits - Account does not have enough credits to perform the operation - 404: Not Found - The requested resource or endpoint does not exist - 408: Timeout - No result has been returned for over 10 minutes. - 422: Validation Error - The request parameters failed validation checks - 429: Rate Limited - Request limit has been exceeded for this resource - 455: Service Unavailable - System is currently undergoing maintenance - 500: Server Error - An unexpected error occurred while processing the request - 501: Generation Failed - Content generation task failed - 505: Feature Disabled - The requested feature is currently disabled
msg	string	是	Response message, error description when failed
data	object	是	—

{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}