suno_underpainting

Instructions

Takes your uploaded vocal track and adds an AI-generated instrumental
accompaniment beneath it (underpainting = adding music under vocals).

Use this when:
- You have a vocal recording and want to add music behind it
- You want to give an acapella track a full musical arrangement
- You need to add instrumental backing to existing vocals

Returns:
    Task ID and the audio with accompaniment added.

Implementation Reference

• tools/audio_tools.py:796-848 (handler)

  The main handler function for suno_underpainting. It is an async MCP tool decorated with @mcp.tool() that accepts an audio_id (uploaded via suno_upload_audio), underpainting_start, underpainting_end, model, and callback_url. It builds a payload with action='underpainting' and calls client.generate_audio(), then formats the result.

  @mcp.tool()
  async def suno_underpainting(
      audio_id: Annotated[
          str,
          Field(
              description="ID of the uploaded audio to add accompaniment to. Must be uploaded via suno_upload_audio."
          ),
      ],
      underpainting_start: Annotated[
          float,
          Field(description="Start time in seconds for adding accompaniment. Default is 0."),
      ] = 0.0,
      underpainting_end: Annotated[
          float | None,
          Field(
              description="End time in seconds for adding accompaniment. Must be less than total song duration."
          ),
      ] = None,
      model: Annotated[
          SunoModel,
          Field(description="Model version to use."),
      ] = DEFAULT_MODEL,
      callback_url: Annotated[
          str | None,
          Field(description="Webhook callback URL for asynchronous notifications."),
      ] = None,
  ) -> str:
      """Add AI-generated accompaniment/instrumental background to uploaded audio.
  
      Takes your uploaded vocal track and adds an AI-generated instrumental
      accompaniment beneath it (underpainting = adding music under vocals).
  
      Use this when:
      - You have a vocal recording and want to add music behind it
      - You want to give an acapella track a full musical arrangement
      - You need to add instrumental backing to existing vocals
  
      Returns:
          Task ID and the audio with accompaniment added.
      """
      payload: dict = {
          "action": "underpainting",
          "audio_id": audio_id,
          "underpainting_start": underpainting_start,
          "model": model,
          "callback_url": callback_url,
      }
  
      if underpainting_end is not None:
          payload["underpainting_end"] = underpainting_end
  
      result = await client.generate_audio(**payload)
      return format_audio_result(result)

• tools/audio_tools.py:797-821 (schema)

  The parameter schema (Pydantic Field annotations) for suno_underpainting defining audio_id (str), underpainting_start (float, default 0.0), underpainting_end (float|None), model (SunoModel enum, default DEFAULT_MODEL), and callback_url (str|None).

  async def suno_underpainting(
      audio_id: Annotated[
          str,
          Field(
              description="ID of the uploaded audio to add accompaniment to. Must be uploaded via suno_upload_audio."
          ),
      ],
      underpainting_start: Annotated[
          float,
          Field(description="Start time in seconds for adding accompaniment. Default is 0."),
      ] = 0.0,
      underpainting_end: Annotated[
          float | None,
          Field(
              description="End time in seconds for adding accompaniment. Must be less than total song duration."
          ),
      ] = None,
      model: Annotated[
          SunoModel,
          Field(description="Model version to use."),
      ] = DEFAULT_MODEL,
      callback_url: Annotated[
          str | None,
          Field(description="Webhook callback URL for asynchronous notifications."),
      ] = None,

• tools/audio_tools.py:796-797 (registration)

  The @mcp.tool() decorator registers suno_underpainting as an MCP tool. The mcp server instance is imported from core.server.

  @mcp.tool()
  async def suno_underpainting(

• main.py:231-233 (registration)

  The tool is also listed in the HTTP server card (server_card endpoint) for tool discovery, with name 'suno_underpainting' and description 'Add AI accompaniment to uploaded vocal audio'.

      "name": "suno_underpainting",
      "description": "Add AI accompaniment to uploaded vocal audio",
  },