{"record":{"id":"87fa4750e0bbae4d","repo":"calesthio/OpenMontage","slug":"kling-avatar-requires-audio-id-sound-file-sound","errorCode":null,"errorMessage":"Kling avatar requires audio_id, sound_file, sound_file_url, sound_file_path, or audio_path","messagePattern":"Kling avatar requires audio_id, sound_file, sound_file_url, sound_file_path, or audio_path","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/avatar/kling_avatar.py","lineNumber":271,"sourceCode":"            \"audio_source\": audio_source,\n        }\n\n    @staticmethod\n    def _copy_audio_input(inputs: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:\n        audio_id = str(inputs.get(\"audio_id\") or \"\").strip()\n        if audio_id:\n            payload[\"audio_id\"] = audio_id\n            return {\"type\": \"audio_id\", \"value\": audio_id}\n\n        sound_path = inputs.get(\"sound_file_path\") or inputs.get(\"audio_path\")\n        sound_file = normalize_media_input(\n            url=inputs.get(\"sound_file_url\"),\n            path=sound_path,\n            value=inputs.get(\"sound_file\"),\n            label=\"Avatar audio file\",\n        )\n        if not sound_file:\n            raise ValueError(\"Kling avatar requires audio_id, sound_file, sound_file_url, sound_file_path, or audio_path\")\n        payload[\"sound_file\"] = sound_file\n        return {\n            \"type\": \"sound_file\",\n            \"source\": inputs.get(\"sound_file_url\") or sound_path or \"inline\",\n        }\n\n    def _download_videos(\n        self,\n        client: KlingClient,\n        outputs: list[dict[str, Any]],\n        inputs: dict[str, Any],\n    ) -> list[Path]:\n        if not outputs:\n            raise ValueError(\"Kling avatar response contained no videos\")\n        base_path = Path(inputs.get(\"output_path\", \"kling_avatar.mp4\"))\n        paths: list[Path] = []\n        for index, item in enumerate(outputs):\n            url = self._output_url(item)","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/avatar/kling_avatar.py#L253-L289","documentation":"ValueError from KlingAvatarTool._copy_audio_input when no audio source is provided. Talking-avatar generation is audio-driven: Kling needs either a previously uploaded audio_id or a sound file (inline value sound_file, URL sound_file_url, or local path sound_file_path/audio_path). normalize_media_input returning falsy means none of the five accepted inputs was usable.","triggerScenarios":"Calling kling_avatar with an image but no audio inputs; passing sound_file_path to a file that does not exist; passing a sound_file_url that is empty or malformed.","commonSituations":"Forgetting the TTS step in the pipeline so no audio path exists; audio step wrote to a different filename; using audio_id from a different Kling account/app so the value is stale.","solutions":["Provide one of: audio_id (from a prior Kling audio upload), sound_file (inline bytes/base64), sound_file_url (public URL), sound_file_path, or audio_path (local file).","Verify local audio files exist and are non-empty before the call.","If using audio_id, confirm it came from a successful upload under the same API key."],"exampleFix":"// before\nresult = tool.run({\"image_path\": \"portrait.png\"})  # no audio\n\n// after\nresult = tool.run({\n    \"image_path\": \"portrait.png\",\n    \"sound_file_path\": \"narration.mp3\",\n})","handlingStrategy":"validation","validationCode":"from pathlib import Path\naudio_ok = any([\n    inputs.get(\"audio_id\"),\n    inputs.get(\"sound_file\"),\n    inputs.get(\"sound_file_url\"),\n    inputs.get(\"sound_file_path\") and Path(inputs[\"sound_file_path\"]).is_file(),\n    inputs.get(\"audio_path\") and Path(inputs[\"audio_path\"]).is_file(),\n])\nassert audio_ok, \"kling_avatar requires one audio source\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run the TTS step before the avatar step and assert its output file exists","Prefer audio_id reuse for repeated generations to avoid re-uploading"],"tags":["kling","avatar","audio","required-field","input-validation"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}