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

# Image to Song

> Generate a song from an image by analyzing it and creating music based on visual content. The process can optionally include custom lyrics, voice conversion, and various musical parameters.



## OpenAPI

````yaml POST /v1/image_to_song
openapi: 3.1.0
info:
  title: Musicgpt API
  version: 1.0.0
  description: API for retrieving conversion details by ID.
servers:
  - url: https://api.musicgpt.com/api/public
    description: Production server
security: []
paths:
  /v1/image_to_song:
    post:
      summary: Generate a Song from an Image
      description: >-
        Generate a song from an image by analyzing it and creating music based
        on visual content. The process can optionally include custom lyrics,
        voice conversion, and various musical parameters.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image_file:
                  type: string
                  format: binary
                  description: >-
                    Image file to upload and analyze. Supported formats: JPEG,
                    PNG, GIF, BMP, WEBP.
                image_url:
                  type: string
                  description: >-
                    URL of the image to analyze. Either this or image_file must
                    be provided.
                  example: https://mybucket.s3.amazonaws.com/image.png
                prompt:
                  type: string
                  description: >-
                    Additional prompt to guide the song generation from the
                    image.
                  maxLength: 300
                  example: Generate a relaxing acoustic track inspired by this scene.
                lyrics:
                  type: string
                  description: Custom lyrics to include in the generated audio.
                  maxLength: 3000
                  example: Let the colors of the sunset fill your heart.
                negative_tags:
                  type: string
                  description: Tags or themes to avoid in the song.
                  example: no heavy metal, avoid loud drums
                make_instrumental:
                  type: boolean
                  description: Generate instrumental output only. Lyrics will be ignored.
                  default: false
                vocal_only:
                  type: boolean
                  description: Generate vocal-only output.
                  default: false
                key:
                  type: string
                  description: Musical key for the song.
                  example: C major
                bpm:
                  type: integer
                  description: >-
                    Beats per minute for the song tempo. Defaults to 0
                    (auto-selected).
                  default: 0
                webhook_url:
                  type: string
                  description: Optional callback URL for async processing results.
                  example: https://example.com/webhook
                voice_id:
                  type: string
                  description: >-
                    Voice ID for converting the generated audio. Cannot be used
                    with vocal_only mode.
              anyOf:
                - required:
                    - image_file
                - required:
                    - image_url
      responses:
        '200':
          description: Successfully initiated image-to-song task
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  task_id:
                    type: string
                  conversion_id_1:
                    type: string
                  conversion_id_2:
                    type: string
                  eta:
                    type: integer
                    description: Estimated processing time in seconds
                  credit_estimate:
                    type: number
                    format: float
                example:
                  success: true
                  message: Message Published To Queue
                  task_id: task_12345
                  conversion_id_1: conv_12345
                  conversion_id_2: conv_54321
                  eta: 300
                  credit_estimate: 150.5
        '422':
          description: Validation Error / Unprocessable Content
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: image_file or image_url is required.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Internal Server Error
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: Python
          source: >-
            import requests


            url = "https://api.musicgpt.com/api/public/v1/image_to_song"

            headers = {"Authorization": "<API_KEY>"}

            data = {
                "image_url": "https://mybucket.s3.amazonaws.com/image.png",
                "prompt": "Generate a relaxing acoustic track inspired by this scene.",
                "lyrics": "Let the colors of the sunset fill your heart.",
                "make_instrumental": False,
                "vocal_only": False,
                "key": "C major",
                "bpm": 120,
                "webhook_url": "https://example.com/webhook",
                "voice_id": "voice_123"
            }


            # Option 1: Using image URL

            response = requests.post(url, headers=headers, data=data)

            print(response.json())


            # Option 2: Uploading a local image file

            # with open("image.png", "rb") as f:

            #     files = {"image_file": f}

            #     response = requests.post(url, headers=headers, data=data,
            files=files)

            #     print(response.json())
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````