{"id":2676,"library":"pyannoteai-sdk","title":"pyannoteAI Python SDK","description":"The official pyannoteAI Python SDK provides a convenient way to interact with the pyannoteAI platform. It offers state-of-the-art AI models for tasks like speaker diarization (who spoke when), speaker identification, and STT orchestration (speech-to-text with speaker attribution) via a cloud API. The library is actively maintained, with frequent releases bringing new features and improvements.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/pyannote/pyannoteAI-python-sdk","tags":["AI","speech processing","speaker diarization","audio","SDK","API client","speech-to-text"],"install":[{"cmd":"pip install pyannoteai-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"HTTP client for API interaction.","package":"requests","optional":false}],"imports":[{"symbol":"Client","correct":"from pyannoteai.sdk import Client"}],"quickstart":{"code":"import os\nfrom pyannoteai.sdk import Client\n\n# Ensure your API key is set as an environment variable or passed directly\n# It's recommended to set PYANNOTE_API_KEY as an environment variable in production\napi_key = os.environ.get('PYANNOTE_API_KEY', 'YOUR_API_KEY_HERE')\n\nif api_key == 'YOUR_API_KEY_HERE':\n    print(\"Warning: Please replace 'YOUR_API_KEY_HERE' with your actual pyannoteAI API key or set the PYANNOTE_API_KEY environment variable.\")\n\nclient = Client(api_key)\n\n# Example audio URL (replace with your audio file accessible via a direct public URL)\naudio_url = \"https://files.pyannote.ai/samples/two_speakers.wav\"\n\ntry:\n    # Submit a diarization job\n    job_id = client.diarize(audio_url)\n    print(f\"Diarization job submitted with ID: {job_id}\")\n\n    # Wait for the job to complete and retrieve results\n    # In a real application, you might use webhooks or polling for job status\n    job_result = client.get_job_result(job_id)\n    \n    if job_result and job_result.get(\"status\") == \"completed\":\n        print(\"Diarization Result:\")\n        for segment in job_result.get(\"output\", {}).get(\"segments\", []):\n            start = segment[\"start\"]\n            end = segment[\"end\"]\n            speaker = segment[\"speaker\"]\n            print(f\"[ {start:.2f}s - {end:.2f}s ] Speaker {speaker}\")\n    else:\n        print(f\"Job {job_id} status: {job_result.get('status')}\")\n        print(f\"Error: {job_result.get('error', 'Unknown error')}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the pyannoteAI client with your API key and submit an audio file for speaker diarization. It then fetches and prints the diarization results. Remember to replace `YOUR_API_KEY_HERE` with a valid key from your pyannoteAI dashboard and use a publicly accessible audio URL."},"warnings":[{"fix":"Store API keys as environment variables and access them using `os.environ.get('PYANNOTE_API_KEY')`.","message":"API keys are sensitive. Do not hardcode them in your codebase or expose them in client-side code or public repositories. It is highly recommended to use environment variables (e.g., `PYANNOTE_API_KEY`) for secure access.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use direct, publicly accessible URLs for audio files. For cloud storage, generate signed URLs if the files are private, or upload them to pyannoteAI's servers directly using the SDK if supported.","message":"The `diarize` and `identify` methods require a direct, publicly accessible URL to your audio file. Indirect URLs (requiring authentication, CAPTCHA, or a landing page) or private cloud storage URLs will result in 'Could not load audio' errors. Ensure the URL points directly to the file itself (e.g., ends with .wav, .mp3).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your audio files adhere to the specified size and duration limits before submitting them. Consider pre-processing or splitting larger files if necessary.","message":"The pyannoteAI API imposes limits on file size and audio duration. Diarization and identification jobs support files up to 1 GiB and 24 hours duration. Voiceprint jobs have tighter limits of 100 MiB and 30 seconds duration.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware that benchmarks and features might differ between the cloud API accessed via this SDK and the locally run open-source `pyannote.audio` library.","message":"The `pyannoteai-sdk` interacts with the pyannoteAI cloud platform, which utilizes premium, improved versions of the pyannote diarization models. These are distinct from the open-source `pyannote.audio` library, offering potentially higher accuracy and speed for specific use cases.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement logic to poll for job completion and download/store the `get_job_result` output promptly.","message":"Job results from the pyannoteAI API are automatically deleted after 24 hours. If you need to retain the results for longer, you must retrieve and save them to your own storage within this timeframe.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}