> ## Documentation Index > Fetch the complete documentation index at: https://docs.sunoapi.org/llms.txt > Use this file to discover all available pages before exploring further. # Generate Suno AI Music This is the key endpoint in the Suno API. Each request returns exactly 2 songs. * Stream URL: Available in 30-40 seconds. * Downloadable song URL: Ready in 2-3 minutes. Concurrency limit: 20 requests every 10 seconds. Exceeding this will result in request rejection. Please review the parameters carefully to ensure proper use. ### Parameter Usage Guide * When customMode is true (Custom Mode): * If instrumental is true: style and title are required * If instrumental is false: style, prompt, and title are required * Prompt length limit: * For V4 model: 3000 characters * For V4\_5, V4\_5PLUS, V4\_5ALL, V5 and V5\_5 models: 5000 characters * Style length limit: * For V4 model: 200 characters * For V4\_5, V4\_5PLUS, V4\_5ALL, V5 and V5\_5 models: 1000 characters * Title length limit: * For V4 and V4\_5ALL model: 80 characters * For V4\_5, V4\_5PLUS, V5 and V5\_5 models: 100 characters * When customMode is false (Non-custom Mode): * Only prompt is required regardless of instrumental setting * prompt length limit: 500 characters * Other parameters should be left empty ### Optional Parameters * personaId (string): Persona ID or Suno Voice `voiceId` to apply in Custom Mode. If you use a Voice-generated ID, set `personaModel` to `voice_persona`. * personaModel (string): Persona type. Use `style_persona` for Generate Persona IDs, or `voice_persona` for Suno Voice IDs. ### Developer Notes 1. Recommendation for First-Time Users: Start with customMode: false and instrumental: false, and only provide a prompt. This is the simplest setup to quickly test the API and experience the results. 2. Generated files are retained for 15 days before being deleted 3. Ensure all required fields are provided based on the customMode and instrumental settings to avoid errors 4. Respect the character limits for prompt, style, and title to ensure successful processing 5. Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete) 6. You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks ## OpenAPI ````yaml suno-api/suno-api.json POST /api/v1/generate openapi: 3.0.0 info: title: intro description: API documentation for audio generation services version: 1.0.0 contact: name: Technical Support email: support@sunoapi.org servers: - url: https://api.sunoapi.org description: API Server security: - BearerAuth: [] tags: - name: Music Generation description: Endpoints for creating and managing music generation tasks - name: Lyrics Generation description: Endpoints for lyrics generation and management - name: WAV Conversion description: Endpoints for converting music to WAV format - name: Vocal Removal description: Endpoints for vocal removal from music tracks - name: Music Video Generation description: Endpoints for generating MP4 videos from music tracks - name: Account Management description: Endpoints for account and credits management paths: /api/v1/generate: post: summary: Generate Music operationId: generate-music requestBody: required: true content: application/json: schema: type: object required: - customMode - instrumental - callBackUrl - model properties: prompt: type: string description: >- A description of the desired audio content. - In Custom Mode (`customMode: true`): Required if `instrumental` is `false`. The prompt will be strictly used as the lyrics and sung in the generated track. Character limits by model: - **V4**: Maximum 3000 characters - **V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5**: Maximum 5000 characters Example: "A calm and relaxing piano track with soft melodies" - In Non-custom Mode (`customMode: false`): Always required. The prompt serves as the core idea, and lyrics will be automatically generated based on it (not strictly matching the input). Maximum 500 characters. Example: "A short relaxing piano tune" example: A calm and relaxing piano track with soft melodies style: type: string description: >- The music style or genre for the audio. - Required in Custom Mode (`customMode: true`). Examples: "Jazz", "Classical", "Electronic". - For V4 model: Max length: 200 characters. - For V4_5, V4_5PLUS, V4_5ALL, V5 and V5_5 models: Max length: 1000 characters. Example: "Classical" - In Non-custom Mode (`customMode: false`): Leave empty. example: Classical title: type: string description: >- The title of the generated music track. - Required in Custom Mode (`customMode: true`). Character limits by model: - **V4 & V4_5ALL**: Maximum 80 characters - **V4_5, V4_5PLUS, V5 & V5_5**: Maximum 100 characters Example: "Peaceful Piano Meditation" - In Non-custom Mode (`customMode: false`): Leave empty. example: Peaceful Piano Meditation customMode: type: boolean description: >- Enables Custom Mode for advanced audio generation settings. - Set to `true` to use Custom Mode (requires `style` and `title`; `prompt` required if `instrumental` is `false`). The prompt will be strictly used as lyrics if `instrumental` is `false`. - Set to `false` for Non-custom Mode (only `prompt` is required). Lyrics will be auto-generated based on the prompt. example: true instrumental: type: boolean description: >- Determines if the audio should be instrumental (no lyrics). - In Custom Mode (`customMode: true`): - If `true`: Only `style` and `title` are required. - If `false`: `style`, `title`, and `prompt` are required (with `prompt` used as the exact lyrics). - In Non-custom Mode (`customMode: false`): No impact on required fields (`prompt` only). Lyrics are auto-generated if `instrumental` is `false`. example: true personaId: type: string description: >- Only available when custom parameters are enabled. Persona ID to apply to the generated music. Optional. You can use either: - A Persona ID generated by the [Generate Persona](https://docs.sunoapi.org/suno-api/generate-persona) endpoint. Use `personaModel: style_persona` or omit `personaModel` to use the default. - A `voiceId` generated by the [Suno Voice](https://docs.sunoapi.org/suno-api/suno-voice-generate) workflow. When using a voice-generated ID, you must set `personaModel: voice_persona`. example: persona_123 personaModel: type: string description: >- Persona model type to apply when using `personaId`. Optional. - `style_persona` (default): Use this for Persona IDs generated by the Generate Persona endpoint. - `voice_persona`: Use this when `personaId` is a `voiceId` generated by Suno Voice. This option is only available with V5 and V5_5 models. enum: - style_persona - voice_persona default: style_persona example: style_persona model: type: string description: |- The model version to use for audio generation. - Available options: - **`V5_5`**: Unleash Your Voice: Custom Models Tailored to Your Unique Taste. - **`V5`**: Superior musical expression, faster generation. - **`V4_5PLUS`**: V4.5+ is richer sound, new ways to create, max 8 min. - **`V4_5ALL`**: V4.5-all is better song structure, max 8 min. - **`V4_5`**: Superior genre blending with smarter prompts and faster output, up to 8 minutes. - **`V4`**: Best audio quality with refined song structure, up to 4 minutes. enum: - V4 - V4_5 - V4_5PLUS - V4_5ALL - V5 - V5_5 example: V4_5ALL duration: type: number description: >- Audio duration in seconds. Optional. Only supported when `model` is `V5_5` and `customMode` is `true`. Range: 10–360 seconds. Must be an integer. minimum: 10 maximum: 360 multipleOf: 1 example: 60 negativeTags: type: string description: >- Music styles or traits to exclude from the generated audio. - Optional. Use to avoid specific styles. Example: "Heavy Metal, Upbeat Drums" example: Heavy Metal, Upbeat Drums vocalGender: type: string description: Preferred vocal gender for generated vocals. Optional. enum: - m - f example: m styleWeight: type: number description: Weight of the provided style guidance. Range 0.00–1.00. minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.65 weirdnessConstraint: type: number description: Constraint on creative deviation/novelty. Range 0.00–1.00. minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.65 audioWeight: type: number description: >- Weight of the input audio influence (where applicable). Range 0.00–1.00. minimum: 0 maximum: 1 multipleOf: 0.01 example: 0.65 callBackUrl: type: string format: uri description: >- The URL to receive task completion notifications when music generation is complete. - For detailed callback format and implementation guide, see [Music Generation Callbacks](https://docs.sunoapi.org/suno-api/generate-music-callbacks) - Alternatively, you can use the get music generation details endpoint to poll task status example: https://api.example.com/callback responses: '200': description: Request successful content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: type: object properties: taskId: type: string description: Task ID for tracking task status example: 5c79****be8e '500': $ref: '#/components/responses/Error' callbacks: audioGenerated: '{request.body#/callBackUrl}': post: description: >- System will call this callback when audio generation is complete. ### Callback Example ```json { "code": 200, "msg": "All generated successfully.", "data": { "callbackType": "complete", "task_id": "2fac****9f72", "data": [ { "id": "8551****662c", "audio_url": "https://example.cn/****.mp3", "source_audio_url": "https://example.cn/****.mp3", "stream_audio_url": "https://example.cn/****", "source_stream_audio_url": "https://example.cn/****", "image_url": "https://example.cn/****.jpeg", "source_image_url": "https://example.cn/****.jpeg", "prompt": "[Verse] Night city lights shining bright", "model_name": "chirp-v3-5", "title": "Iron Man", "tags": "electrifying, rock", "createTime": "2025-01-01 00:00:00", "duration": 198.44 }, { "id": "bd15****1873", "audio_url": "https://example.cn/****.mp3", "source_audio_url": "https://example.cn/****.mp3", "stream_audio_url": "https://example.cn/****", "source_stream_audio_url": "https://example.cn/****", "image_url": "https://example.cn/****.jpeg", "source_image_url": "https://example.cn/****.jpeg", "prompt": "[Verse] Night city lights shining bright", "model_name": "chirp-v3-5", "title": "Iron Man", "tags": "electrifying, rock", "createTime": "2025-01-01 00:00:00", "duration": 228.28 } ] } } ``` requestBody: content: application/json: schema: type: object properties: code: type: integer description: Status code example: 200 msg: type: string description: Response message example: All generated successfully data: type: object properties: callbackType: type: string description: >- Callback type: text (text generation complete), first (first track complete), complete (all tracks complete) enum: - text - first - complete task_id: type: string description: Task ID data: type: array items: type: object properties: id: type: string description: Audio unique identifier (audioId) audio_url: type: string description: Audio file URL source_audio_url: type: string description: Original audio file URL stream_audio_url: type: string description: Streaming audio URL source_stream_audio_url: type: string description: Original streaming audio URL image_url: type: string description: Cover image URL source_image_url: type: string description: Original cover image URL prompt: type: string description: Generation prompt/lyrics model_name: type: string description: Model name used title: type: string description: Music title tags: type: string description: Music tags createTime: type: string description: Creation time format: date-time duration: type: number description: Audio duration (seconds) responses: '200': description: Callback received successfully method: post type: path path: '{request.body#/callBackUrl}' components: schemas: ApiResponse: type: object properties: code: type: integer description: |- # Status Codes - ✅ 200 - Request successful - ⚠️ 400 - Invalid parameters - ⚠️ 401 - Unauthorized access - ⚠️ 404 - Invalid request method or path - ⚠️ 405 - Rate limit exceeded - ⚠️ 413 - Theme or prompt too long - ⚠️ 429 - Insufficient credits - ⚠️ 430 - Your call frequency is too high. Please try again later. - ⚠️ 455 - System maintenance - ❌ 500 - Server error example: 200 enum: - 200 - 400 - 401 - 404 - 405 - 413 - 429 - 430 - 455 - 500 msg: type: string description: Error message when code != 200 example: success responses: Error: description: Server error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- # 🔑 API Authentication All endpoints require authentication using Bearer Token. ## Get API Key 1. Visit the [API Key Management Page](https://sunoapi.org/api-key) to obtain your API Key ## Usage Add to request headers: ``` Authorization: Bearer YOUR_API_KEY ``` > **⚠️ Note:** > - Keep your API Key secure and do not share it with others > - If you suspect your API Key has been compromised, reset it immediately from the management page ````