fix: WAV conversion requires BOTH task_id AND audio_id

CodeKeanu · claude · CodeKeanu · commit 610adc55271f · 2025-11-26T20:19:06.000Z
BREAKING CHANGE: convert_to_wav() now requires both parameters Root cause: Suno API documentation states that BOTH taskId AND audioId are required parameters, not either/or as previously implemented. Changes: - suno_client.py: Made task_id and audio_id required (not optional) - suno_client.py: Updated validation to check both IDs are provided - suno_client.py: Always send both IDs in API payload - suno_client.py: Updated docstring with correct usage example - server.py: Updated MCP tool schema to require both IDs - server.py: Updated handler validation for both required IDs - test_wav_feature.py: Updated validation tests for new signature Tested with real track IDs - conversion now works successfully! Result: {'code': 200, 'msg': 'success', 'data': {'taskId': '...'}} 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/server.py b/server.py
@@ -150,7 +150,7 @@ async def handle_list_tools() -> list[Tool]:
         ),
         Tool(
             name="convert_to_wav",
-            description="Convert a generated audio track to WAV format. Provide EITHER task_id OR audio_id (or both). Using audio_id is recommended for precision when a generation task has multiple tracks. Returns a conversion task ID that can be used to check conversion status.",
+            description="Convert a generated audio track to WAV format. Requires BOTH task_id (generation job ID) AND audio_id (specific track ID). The task_id identifies the generation job, and audio_id specifies which track to convert. Returns a conversion task ID that can be used to check conversion status.",
             inputSchema={
                 "type": "object",
                 "properties": {
@@ -160,14 +160,14 @@ async def handle_list_tools() -> list[Tool]:
                     },
                     "task_id": {
                         "type": "string",
-                        "description": "Original generation task ID (taskId) from generate_music - converts all tracks from that generation (optional if audio_id provided)"
+                        "description": "Generation task ID (taskId) from music['data']['taskId'] - the hex string identifying the generation job (REQUIRED)"
                     },
                     "audio_id": {
                         "type": "string",
-                        "description": "Track ID (audioId) of the specific generated music track to convert - more precise, recommended (optional if task_id provided)"
+                        "description": "Track ID (audioId) from music['data']['sunoData'][0]['id'] - UUID identifying the specific track to convert (REQUIRED)"
                     }
                 },
-                "required": ["callback_url"]
+                "required": ["callback_url", "task_id", "audio_id"]
             }
         ),
         Tool(
@@ -414,10 +414,13 @@ async def handle_call_tool(name: str, arguments: dict | None) -> list[TextConten
             if not callback_url:
                 raise ValueError("callback_url is required")
 
-            if not task_id and not audio_id:
-                raise ValueError("Either task_id or audio_id must be provided")
+            if not task_id:
+                raise ValueError("task_id is required (generation job ID from music['data']['taskId'])")
+
+            if not audio_id:
+                raise ValueError("audio_id is required (track ID from music['data']['sunoData'][0]['id'])")
 
-            # Convert to WAV (pass whichever IDs were provided)
+            # Convert to WAV (BOTH IDs required per Suno API)
             result = await suno_client.convert_to_wav(
                 callback_url=callback_url,
                 task_id=task_id,
diff --git a/suno_client.py b/suno_client.py
@@ -243,48 +243,50 @@ async def get_credits(self) -> Dict[str, Any]:
     async def convert_to_wav(
         self,
         callback_url: str,
-        task_id: str = None,
-        audio_id: str = None
+        task_id: str,
+        audio_id: str
     ) -> Dict[str, Any]:
         """
         Convert a generated audio track to WAV format.
 
-        Per Suno API docs: You can provide EITHER taskId OR audioId to identify the source track.
-        Providing audioId ensures the exact track is converted (recommended when a task has multiple tracks).
+        Per Suno API docs: BOTH taskId AND audioId are REQUIRED parameters.
+        The audioId specifies which exact track to convert (tasks can have multiple tracks).
 
         Args:
             callback_url: Webhook URL for conversion completion notification (required)
-            task_id: Original generation task ID (taskId) from generate_music (optional)
-            audio_id: Track ID (audioId) of the specific track to convert (optional)
+            task_id: Original generation task ID (taskId) from generate_music (required)
+            audio_id: Track ID (audioId) of the specific track to convert (required)
 
         Returns:
             Dictionary containing WAV conversion task information with taskId
 
         Raises:
             SunoAPIError: If the API request fails
-            ValueError: If neither task_id nor audio_id is provided, or if callback_url is missing
+            ValueError: If required parameters are missing or invalid
 
         Example:
-            # Option 1: Convert using audio_id (recommended - more precise)
+            # Generate music and wait for completion
             music = await client.generate_music(prompt="Epic soundtrack", wait_audio=True)
-            track_id = music['data']['sunoData'][0]['id']
-            conversion = await client.convert_to_wav(
-                callback_url="https://example.com/webhook",
-                audio_id=track_id
-            )
 
-            # Option 2: Convert using task_id (converts all tracks from that generation)
-            generation_task_id = music['data']['taskId']
+            # Extract BOTH IDs (both required for WAV conversion)
+            gen_task_id = music['data']['taskId']           # Generation job ID
+            track_id = music['data']['sunoData'][0]['id']   # Specific track ID
+
+            # Convert to WAV (requires both IDs)
             conversion = await client.convert_to_wav(
                 callback_url="https://example.com/webhook",
-                task_id=generation_task_id
+                task_id=gen_task_id,
+                audio_id=track_id
             )
         """
         if not callback_url:
             raise ValueError("callback_url is required for WAV conversion")
 
-        if not task_id and not audio_id:
-            raise ValueError("Either task_id or audio_id must be provided for WAV conversion")
+        if not task_id:
+            raise ValueError("task_id is required for WAV conversion (generation job ID)")
+
+        if not audio_id:
+            raise ValueError("audio_id is required for WAV conversion (specific track ID)")
 
         # Validate callback_url format
         if callback_url:
@@ -313,27 +315,23 @@ async def convert_to_wav(
                 )
 
         # Validate task_id format (should be hex string without dashes, or could have dashes)
-        if task_id:
-            # Task IDs are typically hex strings (with or without dashes)
-            # If user accidentally passes a UUID here, warn them
-            uuid_pattern = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.IGNORECASE)
-            if uuid_pattern.match(task_id):
-                raise ValueError(
-                    f"Possible parameter error: task_id '{task_id}' looks like a UUID (track ID). "
-                    f"If this is a track ID, use the audio_id parameter instead: "
-                    f"convert_to_wav(callback_url=..., audio_id='{task_id}')"
-                )
+        # Task IDs are typically hex strings (with or without dashes)
+        # If user accidentally passes a UUID here, warn them
+        uuid_pattern = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.IGNORECASE)
+        if uuid_pattern.match(task_id):
+            raise ValueError(
+                f"Possible parameter error: task_id '{task_id}' looks like a UUID (track ID). "
+                f"task_id should be the generation job ID (hex string), not a track UUID. "
+                f"Check that you're using task_id from music['data']['taskId'], not from sunoData[]['id']"
+            )
 
-        # Build payload - include whichever ID was provided
+        # Build payload - BOTH IDs are required per API documentation
         payload: Dict[str, Any] = {
-            "callBackUrl": callback_url
+            "callBackUrl": callback_url,
+            "taskId": task_id,
+            "audioId": audio_id
         }
 
-        if task_id:
-            payload["taskId"] = task_id
-        if audio_id:
-            payload["audioId"] = audio_id
-
         try:
             response = await self.client.post("/api/v1/wav/generate", json=payload)
             response.raise_for_status()
diff --git a/test_id_validation.py b/test_id_validation.py
diff --git a/test_wav_feature.py b/test_wav_feature.py
@@ -155,16 +155,21 @@ async def test_validation():
         client = SunoClient()
 
         try:
-            # Test convert_to_wav validation (callback_url required, at least one ID required)
+            # Test convert_to_wav validation (all three params required)
             try:
-                await client.convert_to_wav("", task_id="test_id")
+                await client.convert_to_wav("", "test_task_id", "7752c889-3601-4e55-b805-54a28a53de85")
             except ValueError as e:
                 print(f"  ✓ convert_to_wav validates callback_url: {str(e)}")
 
             try:
-                await client.convert_to_wav("https://example.com/webhook")
+                await client.convert_to_wav("https://example.com/webhook", "", "7752c889-3601-4e55-b805-54a28a53de85")
             except ValueError as e:
-                print(f"  ✓ convert_to_wav validates either task_id or audio_id required: {str(e)}")
+                print(f"  ✓ convert_to_wav validates task_id required: {str(e)}")
+
+            try:
+                await client.convert_to_wav("https://example.com/webhook", "test_task_id", "")
+            except ValueError as e:
+                print(f"  ✓ convert_to_wav validates audio_id required: {str(e)}")
 
             # Test get_wav_conversion_status validation
             try:
