Skip to main content
POST
/
v1
/
voiceprint
Extract voiceprint
curl --request POST \
  --url https://api.pyannote.ai/v1/voiceprint \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/voice.wav",
  "webhook": "https://example.com/webhook",
  "model": "precision-1"
}'
{
  "jobId": "3c8a89a5-dcc6-4edb-a75d-ffd64739674d",
  "status": "created",
  "warning": "<string>"
}
This endpoint allows you to create a new voiceprint from a remote audio URL. The audio file must contain only 1 person speaking. If more than 1 person is found, the voiceprint will be created for the most talkative person. The voiceprint can then be used to create a diarization with speaker identification, see Create Identification.

​
Voiceprint of a remote file (from a URL)

If you have a media file accessible via a URL, you can provide the URL to the file in the request body. Typically you would use this method with a file stored in a cloud storage service such as Amazon S3. If bucket or object is private, you can follow this tutorial and create a signed url to give temporary access. The input audio must also respect the following limits:
  • Maximum duration of 30s
  • Maximum file size of 100MiB
Make sure the URL to the file is publicly and directly accessible, otherwise our endpoint won’t be able to read the file.
Some cloud storage services provide an indirect URL with a confirmation page to access the file. Make sure you provide a direct link to the file instead.

​
Voiceprint of a Local File

If you have a media file stored locally, you can upload it to our temporary media storage and provide the URL to the file in the request body. Typically you would use this method if you have a file stored on a local machine or device. Follow the How to upload files tutorial to upload your file.

​
Receiving the voiceprint (Webhook)

The webhook URL is where the finished voiceprint will be sent. The voiceprint will be sent as a JSON object in the request body.
Make sure the webhook URL is publicly accessible, otherwise our server cannot send the output
Please visit the Webhook documentation for more information on what the webhook sends.

​
Getting results using a webhook

If the optional webhook param is set, the results will be sent to the provided URL. The webhook URL is where any update related to the voiceprint job will be sent. The job output will be sent as a JSON object in the request body.
Make sure the webhook URL is publicly accessible, otherwise our server cannot send the output
Please visit the Receiving webhooks documentation for more information.

​
Polling for job results

As an alternative to webhooks, you can poll the get job endpoint to retrieve job results. To poll for job results, use the status field in the job response to check if the job is completed. Once the job is completed, you can retrieve the job results by accessing the output field.
The output field contains the job results and is only available when the job status is succeeded. Job results are automatically deleted after 24 hours of job completion.
A job is completed when the status field is either succeeded, failed, or canceled.
Be cautious of rate limits when polling. Excessive requests to check job status can lead to rate limiting, potentially disrupting your workflow. Check the rate limits documentation for more information.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
url
string
required

URL of the voiceprint audio file

Example:

"https://example.com/voice.wav"

​
webhook
string

Webhook URL to receive voiceprint results (optional)

Example:

"https://example.com/webhook"

​
model
enum<string>
Available options:
precision-1,
precision-2

Response

​
jobId
string
required

ID of the job

Example:

"3c8a89a5-dcc6-4edb-a75d-ffd64739674d"

​
status
enum<string>
required

Status of the job

Available options:
pending,
created,
succeeded,
canceled,
failed,
running
Example:

"created"

​
warning
string

Warning message if any