> ## Documentation Index > Fetch the complete documentation index at: https://docs.evolink.ai/llms.txt > Use this file to discover all available pages before exploring further. # Suno Music Generation Beta > - Suno AI music generation model, supports generating complete music based on text descriptions or lyrics - Supports custom mode (fine control over style, title, lyrics) and simple mode (AI auto-generation) - Supports [Persona](/en/api-manual/audio-series/suno/suno-persona-creation) for reusable vocal/style characteristics - Asynchronous processing mode, use the returned task ID to [query status](/en/api-manual/task-management/get-task-detail) - Generated audio links are valid for 72 hours, please save them promptly - Each request generates multiple music variations ## OpenAPI ````yaml /en/api-manual/audio-series/suno/suno-music-generation.json POST /v1/audios/generations openapi: 3.1.0 info: title: Suno Music Generation API description: >- Generate music using Suno AI models, supporting both vocal and instrumental modes license: name: MIT version: 1.0.0 servers: - url: https://api.evolink.ai description: Production Environment security: - bearerAuth: [] paths: /v1/audios/generations: post: tags: - Audio Generation summary: Suno Music Generation API description: >- - Suno AI music generation model, supports generating complete music based on text descriptions or lyrics - Supports custom mode (fine control over style, title, lyrics) and simple mode (AI auto-generation) - Supports [Persona](/en/api-manual/audio-series/suno/suno-persona-creation) for reusable vocal/style characteristics - Asynchronous processing mode, use the returned task ID to [query status](/en/api-manual/task-management/get-task-detail) - Generated audio links are valid for 72 hours, please save them promptly - Each request generates multiple music variations operationId: createSunoMusicGeneration requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SunoMusicGenerationRequest' examples: simple_mode: summary: Simple Mode (Recommended for beginners) value: model: suno-v5-beta prompt: A cheerful summer pop song about road trips and freedom custom_mode_with_lyrics: summary: Custom Mode (with lyrics) value: model: suno-v5-beta custom_mode: true instrumental: false style: pop, electronic, upbeat, female vocals, 120bpm title: Summer Dreams prompt: |- [Verse 1] Driving down the highway, windows down The sun is shining on this little town Radio playing our favorite song Nothing could ever go wrong [Chorus] Summer dreams, summer nights Chasing stars and city lights With you by my side I feel so alive negative_tags: heavy metal, screaming, sad vocal_gender: f custom_mode_with_persona: summary: Custom Mode (with Persona) value: model: suno-v5-beta custom_mode: true instrumental: false style: electronic pop, synth wave, 128bpm title: Neon Dreamers prompt: |- [Verse] Walking down the neon street The city's pulse beats in my heart [Chorus] We are the dreamers Dancing under the stars persona_id: 5c57d49ef834110496fae5aa14fec441 persona_model: voice_persona instrumental_mode: summary: Instrumental Mode value: model: suno-v4.5plus-beta custom_mode: true instrumental: true style: lo-fi, chill, ambient, piano, soft drums title: Rainy Afternoon responses: '200': description: Music task created successfully content: application/json: schema: $ref: '#/components/schemas/AudioGenerationResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: Invalid request parameters type: invalid_request_error '401': description: Unauthenticated, invalid or expired token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Invalid or expired token type: authentication_error '402': description: Insufficient quota, recharge required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_quota message: Insufficient quota. Please top up your account. type: insufficient_quota '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: model_access_denied message: 'Token does not have access to model: suno-v5-beta' type: invalid_request_error '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Too many requests, please try again later type: rate_limit_error '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: Internal server error type: api_error '503': description: Service temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: service_unavailable message: No available channel for the requested model type: api_error components: schemas: SunoMusicGenerationRequest: type: object required: - model - custom_mode - instrumental properties: model: type: string description: >- Model name **Backward compatibility:** Previously integrated model names (e.g. `suno-v5`, `suno-v4.5`, `suno-v4.5plus`, `suno-v4.5all`, `suno-v4`) are still supported and will be automatically mapped to the corresponding `-beta` versions **Available options:** - `suno-v5-beta`: V5 latest version (default recommended), supports Voice Persona, superior musical expression, faster generation, prompt max `5000` characters, style max `1000` characters - `suno-v4.5plus-beta`: V4.5+ enhanced version, richer tones, new creative methods, up to 8 minutes, prompt max `5000` characters, style max `1000` characters - `suno-v4.5all-beta`: V4.5 full-featured version, smarter prompts, faster generation, up to 8 minutes, prompt max `5000` characters, style max `1000` characters - `suno-v4.5-beta`: V4.5 version, smarter prompts, faster generation, up to 8 minutes, prompt max `5000` characters, style max `1000` characters - `suno-v4-beta`: V4 version, improved vocal quality, up to 4 minutes, prompt max `3000` characters, style max `200` characters enum: - suno-v5-beta - suno-v4.5plus-beta - suno-v4.5all-beta - suno-v4.5-beta - suno-v4-beta example: suno-v5-beta custom_mode: type: boolean description: >- Enable custom mode **Description:** - `false`: Simple mode, only provide `prompt`, AI auto-generates lyrics and style - `true`: Custom mode, allows fine control over `style`, `title`, lyrics, etc. **Required parameters in custom mode:** - `style`: Required - `title`: Required - `prompt`: Required when `instrumental=false` (used as lyrics) example: false instrumental: type: boolean description: |- Generate instrumental music (no vocals) **Description:** - `false`: Generate music with vocals - `true`: Generate instrumental/background music without vocals **Note:** - In non-custom mode, this parameter doesn't affect required fields - In custom mode, when set to `true`, `prompt` becomes optional example: false prompt: type: string description: >- Prompt describing the desired music content **Non-custom mode (`custom_mode=false`):** - Required, serves as music description, AI auto-generates lyrics and style - Max length: `500` characters **Custom mode (`custom_mode=true`):** - Required when `instrumental=false`, used as exact lyrics - Optional when `instrumental=true` - Max length: `3000` characters for V4, `5000` characters for V4.5+ **Lyrics format suggestions:** - Use tags like `[Verse]`, `[Chorus]`, `[Bridge]` to organize lyrics structure example: A cheerful summer pop song about road trips and freedom style: type: string description: >- Music style specification **Description:** - Required in custom mode (`custom_mode=true`) - Defines the genre, mood, or artistic direction of the music - Recommended to use comma-separated tags in English **Character limits:** - V4: Max `200` characters - V4.5+: Max `1000` characters **Common style tags:** - Genres: pop, rock, jazz, classical, electronic, hip-hop, r&b, country, folk - Moods: happy, sad, energetic, calm, romantic, dark, uplifting - Instruments: piano, guitar, drums, bass, violin, saxophone, synthesizer - Vocals: male vocals, female vocals, choir, harmonies - Tempo: slow, fast, upbeat, groovy, 120bpm example: pop, electronic, upbeat, female vocals title: type: string description: |- Song title **Description:** - Required in custom mode (`custom_mode=true`) - Will be displayed in the player interface and filename - Max length: `80` characters maxLength: 80 example: Summer Dreams negative_tags: type: string description: |- Excluded styles, specify music styles or features to avoid **Examples:** - `heavy metal, screaming, sad` - `rap, fast tempo` example: heavy metal, screaming vocal_gender: type: string description: >- Vocal gender preference **Options:** - `m`: Male voice - `f`: Female voice **Note:** - Only effective when `custom_mode=true` - This parameter only increases the probability, cannot guarantee the specified gender will be followed enum: - m - f example: f style_weight: type: number description: |- Style weight, controls adherence to the specified style **Range:** `0.0` ~ `1.0`, one decimal place **Description:** - Higher values result in closer adherence to specified style - Value of `0` is treated as unset minimum: 0 maximum: 1 example: 0.7 weirdness_constraint: type: number description: >- Weirdness constraint, controls the creativity/experimental degree of the output **Range:** `0.0` ~ `1.0`, one decimal place **Description:** - Higher values result in more creative and experimental output - Lower values result in more traditional and conservative output - Value of `0` is treated as unset minimum: 0 maximum: 1 example: 0.3 audio_weight: type: number description: |- Audio weight, controls the weight of audio features **Range:** `0.0` ~ `1.0`, one decimal place **Description:** - Value of `0` is treated as unset minimum: 0 maximum: 1 example: 0.5 persona_id: type: string description: >- Persona ID to apply a previously created Persona style to this music generation Only available when `custom_mode=true`. Obtained via the [Suno Persona Creation](/en/api-manual/audio-series/suno/suno-persona-creation) API, preserves consistent vocal and style characteristics **How to obtain:** After the Persona creation task completes, retrieve from `result_data.persona_id` example: 5c57d49ef834110496fae5aa14fec441 persona_model: type: string description: >- Persona application mode **Options:** 1. `style_persona`: Style-oriented, emphasizes musical style characteristics (arrangement, rhythm, timbre), supports all model versions 2. `voice_persona`: Voice-oriented, emphasizes vocal characteristics (timbre, singing style, voice), **V5 only** Only available when `custom_mode=true`, typically used with `persona_id`. When using `voice_persona`, the model must be `suno-v5-beta`, otherwise an error is returned enum: - style_persona - voice_persona example: style_persona callback_url: type: string description: >- HTTPS callback URL for task completion notification **Callback stages:** - Callback process has three stages: `text` (text generation), `first` (first track completed), `complete` (all completed) - In some cases, `text` and `first` stages may be skipped, returning `complete` directly **Security restrictions:** - Only HTTPS protocol supported - Callbacks to internal IP addresses are prohibited - URL length must not exceed `2048` characters **Callback mechanism:** - Timeout: `10` seconds - Max `3` retries on failure - Callback URL returning 2xx status code is considered successful format: uri example: https://your-domain.com/webhooks/suno-callback AudioGenerationResponse: type: object properties: created: type: integer description: Task creation timestamp example: 1766319090 id: type: string description: Task ID, used to query task status and results example: task-unified-1766319089-oqs9cue4 model: type: string description: Actual model name used example: suno-v5-beta object: type: string enum: - audio.generation.task description: Task type progress: type: integer description: Task progress percentage (0-100) minimum: 0 maximum: 100 example: 0 status: type: string description: Task status enum: - pending - processing - completed - failed example: pending task_info: $ref: '#/components/schemas/AudioTaskInfo' description: Audio task details type: type: string enum: - audio description: Task output type example: audio usage: $ref: '#/components/schemas/Usage' description: Usage and billing information ErrorResponse: type: object properties: error: type: object properties: code: type: string description: Error code identifier message: type: string description: Error description type: type: string description: Error type AudioTaskInfo: type: object properties: can_cancel: type: boolean description: Whether the task can be cancelled example: true estimated_time: type: integer description: Estimated completion time (seconds) example: 120 Usage: type: object description: Usage and billing information properties: billing_rule: type: string description: Billing rule enum: - per_call - per_token - per_second example: per_call credits_reserved: type: number description: Estimated credits consumed minimum: 0 example: 10 user_group: type: string description: User group enum: - default - vip example: default securitySchemes: bearerAuth: type: http scheme: bearer description: >- ##All APIs require Bearer Token authentication## **Get API Key:** Visit [API Key Management Page](https://evolink.ai/dashboard/keys) to get your API Key **Add to request header:** ``` Authorization: Bearer YOUR_API_KEY ``` ````