> ## 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.

Generate a song from an image by analyzing its content and creating music based on visual cues. Users can optionally provide custom lyrics, select a musical key, adjust tempo, or request instrumental/vocal-only outputs.

***

## Endpoint

```http theme={null}
POST /v1/image_to_song
```

This endpoint processes an image (uploaded or via URL) to generate a song. The image is analyzed to create a descriptive prompt, which is then used to generate AI-driven music.

## Request Parameters

| Parameter           | Type         | Required | Description                                                                     |
| ------------------- | ------------ | -------- | ------------------------------------------------------------------------------- |
| `image_file`        | `UploadFile` | Optional | Upload the image to analyze. Required if `image_url` is not provided.           |
| `image_url`         | `String`     | Optional | Public or S3 URL to the input image. Required if `image_file` is not provided.  |
| `prompt`            | `String`     | Optional | Additional text to guide the song generation (max 300 characters).              |
| `lyrics`            | `String`     | Optional | Custom lyrics to include in the generated audio (max 3000 characters).          |
| `negative_tags`     | `String`     | Optional | Tags or themes to avoid in the song.                                            |
| `make_instrumental` | `Boolean`    | Optional | If true, generates an instrumental version. Defaults to false.                  |
| `vocal_only`        | `Boolean`    | Optional | If true, generates a vocal-only version. Defaults to false.                     |
| `key`               | `String`     | Optional | Musical key for the song (e.g., "C major", "A minor").                          |
| `bpm`               | `Integer`    | Optional | Tempo in beats per minute. Defaults to 0 (auto-selected).                       |
| `webhook_url`       | `String`     | Optional | Callback URL for async result delivery.                                         |
| `voice_id`          | `String`     | Optional | Voice ID for converting generated audio. Cannot be used with `vocal_only` mode. |

> 💡 **Note:** You must provide either `audio_file` or `audio_url` — at least one is required.

> **content-type:** multipart/form-data

***

## Try it Yourself

Visit the [image\_to\_song Endpoint Explorer](/api-documentation/endpoint/imagetosong) to play around — set your payload, hit send, and listen to the generated results live.

## Sample Request

### cURL

```bash theme={null}
curl -X POST "https://api.musicgpt.com/api/public/v1/image_to_song" \
-H "accept: application/json" \
-H "Authorization: <api_key>" \
-F "image_file=@/path/to/image.png" \
-F "prompt=Generate a relaxing acoustic track inspired by this scene." \
-F "lyrics=Let the colors of the sunset fill your heart." \
-F "make_instrumental=false" \
-F "vocal_only=false" \
-F "key=C major" \
-F "bpm=120" \
-F "webhook_url=https://example.com/webhook" \
-F "voice_id=voice_123"
```

### Python

```python theme={null}
import requests

url = "https://api.musicgpt.com/api/public/v1/image_to_song"
headers = {"Authorization": "<API_KEY>"}
data = {
    "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: image_url
files = {}
data["image_url"] = "https://mybucket.s3.amazonaws.com/image.png"
response = requests.post(url, headers=headers, data=data, files=files)

# Option 2: File Upload
# with open("image.png", "rb") as f:
#     files = {"image_file": f}
#     response = requests.post(url, headers=headers, data=data, files=files)

print(response.json())
```

> 🔐 Replace `{path_to_your_audio_file}`, `api_key`, and `webhook_url` before executing.

***

## Sample Response

### Success (200 OK)

```json theme={null}
{
  "success": true,
  "message": "Message Published To Queue",
  "task_id": "task-xyz-123",
  "conversion_id_1": "image-abc",
  "conversion_id_2": "image-def",
  "eta": 40,
  "credit_estimate": 45
}
```

***

## Webhook Delivery

Once the generation is complete, **webhooks** will be triggered to deliver the following:

#### Standard Requests :

* 2 (webhooks) x conversion details (one per version)
* 2 (webhooks) x Lyrics with timestamp data
* 1 Album Cover Image

> Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc.

***

## Common Errors

* **422 Unprocessable Entity**: Missing required fields like `prompt`, `replace_start_at`, or `replace_end_at`, or neither `audio_file` nor `audio_url` provided.
* **500 Internal Server Error**: An unexpected error occurred during processing.

***

The response provides a downloadable audio file.

***


## 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

````