> ## Documentation Index > Fetch the complete documentation index at: https://docs.topmediai.com/llms.txt > Use this file to discover all available pages before exploring further. # V3 Generate Music > Generate music with or without lyrics using AI models. ## OpenAPI ````yaml https://api.topmediai.com/topmediai_api.json post /v3/music/generate openapi: 3.1.0 info: title: Topmediai API Documentation description: >- This is the documentation for the Topmediai API. You can use this API to use our service programmatically, this is done by using your x-api-key. You can get your x-api-key by request our Get API Key Web page on https://www.topmediai.com/api/text-to-speech-api/. Our API is experimental so all endpoints are subject to change. version: 1.0.0 servers: - url: https://api.topmediai.com security: [] paths: /v3/music/generate: post: tags: - AI-Music-Generator summary: V3 Generate Music description: Generate music with or without lyrics using AI models. operationId: generate_song_v3_music_generate_post parameters: - name: x-api-key in: header required: false schema: type: string title: X-Api-Key requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/AutoGenerateRequest' - $ref: '#/components/schemas/CustomGenerateRequest' - $ref: '#/components/schemas/ExtendGenerateRequest' - $ref: '#/components/schemas/ConcatGenerateRequest' - $ref: '#/components/schemas/UploadGenerateRequest' - $ref: '#/components/schemas/UploadExtendGenerateRequest' - $ref: '#/components/schemas/ArtistGenerateRequest' discriminator: propertyName: action mapping: auto: '#/components/schemas/AutoGenerateRequest' custom: '#/components/schemas/CustomGenerateRequest' extend: '#/components/schemas/ExtendGenerateRequest' concat: '#/components/schemas/ConcatGenerateRequest' upload: '#/components/schemas/UploadGenerateRequest' upload_extend: '#/components/schemas/UploadExtendGenerateRequest' artist_consistency: '#/components/schemas/ArtistGenerateRequest' title: Body responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: AutoGenerateRequest: properties: action: type: string const: auto title: Action description: >- Generate songs based on input description words, creating songs of different styles according to the provided description words. style: anyOf: - type: string - type: 'null' title: Style description: > The prompt parameter is used to control the melody, tune, style, and so on of the entire song. example: Happy songs mv: type: string enum: - v5.0 - v4.5-plus - v4.5 - v4.0 - v3.5 - v3.0 title: Mv description: >- v5.0: Generates songs with the most realistic vocals, delivering natural tone and lifelike expression. v4.5-plus: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. Leveraging the latest and most powerful music generation models, it delivers richer sound quality and faster generation speeds. v4.5: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. It boasts studio-quality sound, optimal genre fusion, and faster generation speeds. v4.0: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are more vivid and sound better. v3.5: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are smoother and more engaging. v3.0: Generates songs up to 2 minutes long and supports lyrics inputs of up to 1,000 words. The credit deduction rules for song generation with different models are as follows: When using the V3.0/V3.5/V4.0 models, 2 credits will be deducted each time 2 songs are generated; when using the V4.5/V4.5 Plus models, 3 credits will be deducted each time 2 songs are generated. example: v3.5 exclude_unset: true instrumental: anyOf: - type: integer maximum: 1 minimum: 0 - type: 'null' title: Instrumental description: > The instrumental parameter is used to control whether the song is pure music or not. When instrumental is set to 1, the lyrics parameter will not be applied, even if it is included in your request default: 0 example: 0 gender: anyOf: - type: string enum: - male - female - '' - type: 'null' title: Gender description: | Voice gender preference, used to control the gender of the singer. type: object required: - action title: AutoGenerateRequest CustomGenerateRequest: properties: action: type: string const: custom title: Action description: >- Generate songs with customized lyrics, controlling the generation effect of the songs based on the lyrics, style and title. mv: type: string enum: - v5.0 - v4.5-plus - v4.5 - v4.0 - v3.5 - v3.0 title: Mv description: >- v5.0: Generates songs with the most realistic vocals, delivering natural tone and lifelike expression. v4.5-plus: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. Leveraging the latest and most powerful music generation models, it delivers richer sound quality and faster generation speeds. v4.5: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. It boasts studio-quality sound, optimal genre fusion, and faster generation speeds. v4.0: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are more vivid and sound better. v3.5: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are smoother and more engaging. v3.0: Generates songs up to 2 minutes long and supports lyrics inputs of up to 1,000 words. The credit deduction rules for song generation with different models are as follows: When using the V3.0/V3.5/V4.0 models, 2 credits will be deducted each time 2 songs are generated; when using the V4.5/V4.5 Plus models, 3 credits will be deducted each time 2 songs are generated. example: v3.5 exclude_unset: true instrumental: anyOf: - type: integer maximum: 1 minimum: 0 - type: 'null' title: Instrumental description: > The instrumental parameter is used to control whether the song is pure music or not. When instrumental is set to 1, the lyrics parameter will not be applied, even if it is included in your request default: 0 example: 0 style: anyOf: - type: string - type: 'null' title: Style description: > The prompt parameter is used to control the melody, tune, style, and so on of the entire song. example: Happy songs lyrics: anyOf: - type: string - type: 'null' title: Lyrics description: > The lyrics parameter controls what the song is about, If this field is set to None, then pure music will be generated. example: a good day title: anyOf: - type: string maxLength: 80 - type: 'null' title: Title description: | Create a title for the song you're writing. default: '' example: AI Music exclude_unset: true gender: anyOf: - type: string enum: - male - female - '' - type: 'null' title: Gender description: | Voice gender preference, used to control the gender of the singer. type: object required: - action title: CustomGenerateRequest ExtendGenerateRequest: properties: action: type: string const: extend title: Action description: >- Continue writing songs, generating additional suitable song segments for a specific song. mv: type: string enum: - v5.0 - v4.5-plus - v4.5 - v4.0 - v3.5 - v3.0 title: Mv description: >- v5.0: Generates songs with the most realistic vocals, delivering natural tone and lifelike expression. v4.5-plus: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. Leveraging the latest and most powerful music generation models, it delivers richer sound quality and faster generation speeds. v4.5: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. It boasts studio-quality sound, optimal genre fusion, and faster generation speeds. v4.0: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are more vivid and sound better. v3.5: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are smoother and more engaging. v3.0: Generates songs up to 2 minutes long and supports lyrics inputs of up to 1,000 words. The credit deduction rules for song generation with different models are as follows: When using the V3.0/V3.5/V4.0 models, 2 credits will be deducted each time 2 songs are generated; when using the V4.5/V4.5 Plus models, 3 credits will be deducted each time 2 songs are generated. example: v3.5 exclude_unset: true instrumental: anyOf: - type: integer maximum: 1 minimum: 0 - type: 'null' title: Instrumental description: > The instrumental parameter is used to control whether the song is pure music or not. When instrumental is set to 1, the lyrics parameter will not be applied, even if it is included in your request default: 0 example: 0 style: anyOf: - type: string - type: 'null' title: Style description: > The prompt parameter is used to control the melody, tune, style, and so on of the entire song. example: Happy songs lyrics: anyOf: - type: string - type: 'null' title: Lyrics description: > The lyrics parameter controls what the song is about, If this field is set to None, then pure music will be generated. example: a good day title: anyOf: - type: string maxLength: 80 - type: 'null' title: Title description: | Create a title for the song you're writing. default: '' example: AI Music exclude_unset: true gender: anyOf: - type: string enum: - male - female - '' - type: 'null' title: Gender description: | Voice gender preference, used to control the gender of the singer. continue_at: anyOf: - type: integer - type: number - type: 'null' title: Continue At description: > This field is used in the continuation function and is used to control from which point in the current song the continuation should start. exclude_unset: true continue_song_id: anyOf: - type: string - type: 'null' title: Continue Song Id description: | This parameter tells us which song you want to extend. exclude_unset: true type: object required: - action title: ExtendGenerateRequest ConcatGenerateRequest: properties: action: type: string const: concat title: Action description: Upload custom audio and convert it into an operable song. continue_song_id: type: string title: Continue Song Id description: >- Merge songs and combine multiple continuation segments into a complete song. type: object required: - action - continue_song_id title: ConcatGenerateRequest UploadGenerateRequest: properties: action: type: string const: upload title: Action description: Upload custom audio and convert it into an operable song. audio_url: type: string title: Audio Url description: >- Custom audio upload, capable of identifying the lyric style in the audio and converting it into an operable song. type: object required: - action - audio_url title: UploadGenerateRequest UploadExtendGenerateRequest: properties: action: type: string const: upload_extend title: Action description: Continue writing the uploaded songs and obtain more song segments. mv: type: string enum: - v5.0 - v4.5-plus - v4.5 - v4.0 - v3.5 - v3.0 title: Mv description: >- v5.0: Generates songs with the most realistic vocals, delivering natural tone and lifelike expression. v4.5-plus: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. Leveraging the latest and most powerful music generation models, it delivers richer sound quality and faster generation speeds. v4.5: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. It boasts studio-quality sound, optimal genre fusion, and faster generation speeds. v4.0: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are more vivid and sound better. v3.5: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are smoother and more engaging. v3.0: Generates songs up to 2 minutes long and supports lyrics inputs of up to 1,000 words. The credit deduction rules for song generation with different models are as follows: When using the V3.0/V3.5/V4.0 models, 2 credits will be deducted each time 2 songs are generated; when using the V4.5/V4.5 Plus models, 3 credits will be deducted each time 2 songs are generated. example: v3.5 exclude_unset: true instrumental: anyOf: - type: integer maximum: 1 minimum: 0 - type: 'null' title: Instrumental description: > The instrumental parameter is used to control whether the song is pure music or not. When instrumental is set to 1, the lyrics parameter will not be applied, even if it is included in your request default: 0 example: 0 style: anyOf: - type: string - type: 'null' title: Style description: > The prompt parameter is used to control the melody, tune, style, and so on of the entire song. example: Happy songs lyrics: anyOf: - type: string - type: 'null' title: Lyrics description: > The lyrics parameter controls what the song is about, If this field is set to None, then pure music will be generated. example: a good day title: anyOf: - type: string maxLength: 80 - type: 'null' title: Title description: | Create a title for the song you're writing. default: '' example: AI Music exclude_unset: true gender: anyOf: - type: string enum: - male - female - '' - type: 'null' title: Gender description: | Voice gender preference, used to control the gender of the singer. continue_at: anyOf: - type: integer - type: number - type: 'null' title: Continue At description: > This field is used in the continuation function and is used to control from which point in the current song the continuation should start. exclude_unset: true continue_song_id: anyOf: - type: string - type: 'null' title: Continue Song Id description: |2- This field must be obtained through the upload action, This parameter tells us which song you want to extend, Either the audio_url parameter or the continue_song_id parameter can be used, and the former will be given priority.. exclude_unset: true audio_url: anyOf: - type: string - type: 'null' title: Audio Url description: >- specifies the upload location for audio files; Ensure uploaded audio does not exceed 8 minutes, Either the audio_url parameter or the continue_song_id parameter can be used, and the former will be given priority. type: object required: - action title: UploadExtendGenerateRequest ArtistGenerateRequest: properties: action: type: string const: artist_consistency title: Action description: Generate songs with specific tones based on the singer_id. mv: type: string enum: - v5.0 - v4.5-plus - v4.5 - v4.0 - v3.5 - v3.0 title: Mv description: >- v5.0: Generates songs with the most realistic vocals, delivering natural tone and lifelike expression. v4.5-plus: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. Leveraging the latest and most powerful music generation models, it delivers richer sound quality and faster generation speeds. v4.5: Generates songs up to 8 minutes long and supports lyrics inputs of up to 5,000 words. It boasts studio-quality sound, optimal genre fusion, and faster generation speeds. v4.0: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are more vivid and sound better. v3.5: Generates songs up to 4 minutes long and supports lyrics inputs of up to 3,000 words. Songs are smoother and more engaging. v3.0: Generates songs up to 2 minutes long and supports lyrics inputs of up to 1,000 words. The credit deduction rules for song generation with different models are as follows: When using the V3.0/V3.5/V4.0 models, 2 credits will be deducted each time 2 songs are generated; when using the V4.5/V4.5 Plus models, 3 credits will be deducted each time 2 songs are generated. example: v3.5 exclude_unset: true instrumental: anyOf: - type: integer maximum: 1 minimum: 0 - type: 'null' title: Instrumental description: > The instrumental parameter is used to control whether the song is pure music or not. When instrumental is set to 1, the lyrics parameter will not be applied, even if it is included in your request default: 0 example: 0 style: anyOf: - type: string - type: 'null' title: Style description: > The prompt parameter is used to control the melody, tune, style, and so on of the entire song. example: Happy songs lyrics: anyOf: - type: string - type: 'null' title: Lyrics description: > The lyrics parameter controls what the song is about, If this field is set to None, then pure music will be generated. example: a good day title: anyOf: - type: string maxLength: 80 - type: 'null' title: Title description: | Create a title for the song you're writing. default: '' example: AI Music exclude_unset: true gender: anyOf: - type: string enum: - male - female - '' - type: 'null' title: Gender description: | Voice gender preference, used to control the gender of the singer. singer_id: type: string title: Singer Id description: >- 该字段来源于/v3/music/generate-singer, Used to specify the vocal tone of the singer to generate a song type: object required: - action - singer_id title: ArtistGenerateRequest HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````