> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infery.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Music

> Generate full songs from a prompt.

```bash theme={null}
curl https://api.infery.ai/v1/music/generations \
  -H "Authorization: Bearer $INFERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v4",
    "prompt": "Upbeat indie folk about a sunrise coastal drive",
    "duration_seconds": 60
  }'
```

Music generation is async — returns `job_id`, poll `GET /v1/music/generations/:job_id` for progress.

When complete you get a URL to the MP3 and separate stems if the model exposes them (Suno supports vocals + instrumentals).

### Sample output

<video controls src="https://mintcdn.com/inferyai/5YDpMTITcUUspdCA/samples/music.mp3?fit=max&auto=format&n=5YDpMTITcUUspdCA&q=85&s=51fbabfb08030b46cedcd502720022cd" style={{ width: '100%', maxWidth: 480, height: 54 }} data-path="samples/music.mp3" />

*30-second clip generated with `lyria-3-clip-preview` (Google Lyria).*

## Parameters

* `prompt` — natural-language description
* `style` — optional style tag (`lofi`, `synthwave`, `indie`, etc.)
* `lyrics` — optional explicit lyrics
* `vocal_gender` — `male`, `female`, `none`
* `duration_seconds` — 30–180 (model-dependent)

## Supported models

Suno (primary). Google Lyria when in beta. See [Models](/models/catalog) → Music.


## OpenAPI

````yaml openapi.json POST /v1/music/generations
openapi: 3.0.0
info:
  title: Infery Gateway
  description: >-
    Infery Inference Gateway — OpenAI-compatible API for LLMs, embeddings,
    images, audio, and video
  version: '1.0'
  contact: {}
servers:
  - url: https://api.infery.ai
    description: Production
  - url: http://localhost:3001
    description: Local
security: []
tags: []
paths:
  /v1/music/generations:
    post:
      tags:
        - Music
      summary: Generate music from text prompt
      operationId: createMusicGeneration
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - prompt
              properties:
                model:
                  type: string
                  description: Model ID to use for music generation
                prompt:
                  type: string
                  description: >-
                    Text prompt describing the music. For Lyria 3 Clip, always
                    produces 30s. For Lyria 3 Pro, control duration via prompt
                    or timestamps. For Suno, max 500 chars in non-custom mode,
                    up to 5000 in custom mode.
                operation:
                  type: string
                  enum:
                    - generate
                    - extend
                    - upload_cover
                    - upload_extend
                    - add_instrumental
                    - add_vocals
                    - sounds
                    - vocal_removal
                    - lyrics
                  default: generate
                  description: >-
                    Suno operation type. Default = generate. Other operations
                    require additional fields (audio_id, upload_url, etc).
                images:
                  type: array
                  description: >-
                    Up to 10 base64-encoded images to inspire the music (Lyria 3
                    only)
                  items:
                    type: object
                    required:
                      - data
                    properties:
                      data:
                        type: string
                        description: Base64-encoded image data
                      mime_type:
                        type: string
                        enum:
                          - image/jpeg
                          - image/png
                          - image/webp
                          - image/gif
                        default: image/jpeg
                response_format:
                  type: string
                  enum:
                    - mp3
                    - wav
                  default: mp3
                  description: Output format. WAV only supported by Lyria 3 Pro and Suno.
                custom_mode:
                  type: boolean
                  description: >-
                    Suno: Enable custom mode (full control over
                    style/title/lyrics)
                instrumental:
                  type: boolean
                  description: 'Suno: Generate instrumental track only (no vocals)'
                title:
                  type: string
                  description: 'Suno: Track title (custom mode, max 100 chars)'
                style:
                  type: string
                  description: 'Suno: Music genre/style (custom mode, max 1000 chars)'
                lyrics:
                  type: string
                  description: 'Suno: Lyrics text (custom mode, when not instrumental)'
                negative_tags:
                  type: string
                  description: 'Suno: Styles to exclude (e.g. "Heavy Metal, Upbeat Drums")'
                vocal_gender:
                  type: string
                  enum:
                    - m
                    - f
                  description: 'Suno: Preferred vocal gender'
                style_weight:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: 'Suno: Style adherence weight (0.0-1.0)'
                weirdness_constraint:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: 'Suno: Creativity/novelty constraint (0.0-1.0)'
                audio_weight:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: 'Suno: Input audio influence weight (0.0-1.0)'
                persona_id:
                  type: string
                  description: 'Suno: Persona ID to apply (custom mode)'
                persona_model:
                  type: string
                  enum:
                    - style_persona
                    - voice_persona
                  description: 'Suno: Persona model type'
                audio_id:
                  type: string
                  description: 'Suno: Source audio ID (for extend, vocal_removal)'
                task_id:
                  type: string
                  description: >-
                    Suno: Task ID (vocal_removal — references original
                    generation task)
                upload_url:
                  type: string
                  description: >-
                    Suno: Audio file URL (for upload_cover, upload_extend,
                    add_instrumental, add_vocals)
                continue_at:
                  type: number
                  description: 'Suno: Continue from this second mark (extend operations)'
                default_param_flag:
                  type: boolean
                  description: 'Suno: Use default params (extend operations)'
                separation_type:
                  type: string
                  enum:
                    - separate_vocal
                    - split_stem
                  description: 'Suno: Vocal removal type (2 stems vs up to 12 stems)'
                tags:
                  type: string
                  description: 'Suno: Tags for add_instrumental operation'
                sound_loop:
                  type: boolean
                  description: 'Suno sounds: Loop the generated sound'
                sound_tempo:
                  type: integer
                  minimum: 1
                  maximum: 300
                  description: 'Suno sounds: BPM (1-300)'
                sound_key:
                  type: string
                  description: 'Suno sounds: Musical key'
      responses:
        '200':
          description: >-
            Music generation result. Audio is uploaded to private storage and
            returned as a signed `url` (7-day expiry). If the storage upload
            fails, the response falls back to inline `b64_audio`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  created:
                    type: integer
                    example: 1713204900
                    description: Unix timestamp (seconds) when the generation completed
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          example: >-
                            https://storage.googleapis.com/.../music/...mp3?X-Goog-Signature=...
                          description: >-
                            Signed URL to the generated audio (private, 7-day
                            expiry). Primary field.
                        b64_audio:
                          type: string
                          description: >-
                            Base64-encoded audio bytes. Present only when GCS
                            upload fails or on providers that return inline
                            bytes exclusively.
                        content_type:
                          type: string
                          example: audio/mpeg
                          description: >-
                            MIME type of the audio (audio/mpeg for Lyria, varies
                            per provider)
                        duration_seconds:
                          type: number
                          example: 30
                          description: Parsed duration of the generated track
                        lyrics:
                          type: string
                          description: Generated lyrics (Suno only, when requested)
                  credits_used:
                    type: integer
                    example: 180
                    description: >-
                      Credits deducted from the workspace balance for this
                      request
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
      security:
        - ApiKey: []
components:
  schemas:
    ErrorResponseDto:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetailDto'
      required:
        - error
    ErrorDetailDto:
      type: object
      properties:
        message:
          type: string
          example: Model not found
          description: Human-readable error message
        type:
          type: string
          example: invalid_request_error
          description: Error category
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - quota_exceeded
            - rate_limit_error
            - server_error
        code:
          type: object
          example: model_not_found
          nullable: true
          description: Stable machine-readable error code
        param:
          type: object
          example: model
          nullable: true
          description: >-
            Name of the request parameter that triggered the error, if
            applicable
      required:
        - message
        - type
        - code
        - param
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key in format: Bearer inf_***'

````