> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyannote.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Identification Job

This endpoint allows you to create a new diarization with speaker identification from a remote audio URL.

For a complete guide on speaker identification using voiceprints, see the [Identification with Voiceprints](/tutorials/identification-with-voiceprints) tutorial.


## OpenAPI

````yaml POST /v1/identify
openapi: 3.0.0
info:
  title: pyannoteAI API
  description: ''
  version: local
  contact: {}
  termsOfService: https://pyannote.ai/terms-of-use
servers:
  - url: https://api.pyannote.ai
security: []
tags: []
externalDocs:
  description: pyannoteAI Docs
  url: https://docs.pyannote.ai/
paths:
  /v1/identify:
    post:
      tags:
        - Api
        - Operations
      summary: Identify speaker with diarization
      operationId: identify
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentifyRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreated'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '402':
          description: Subscription is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - api-key: []
components:
  schemas:
    IdentifyRequest:
      type: object
      properties:
        url:
          type: string
          description: URL of the audio file to be processed
          example: https://example.com/audio.wav
        webhook:
          type: string
          description: Webhook URL to receive results when job is completed (optional)
          example: https://example.com/webhook
        webhookStatusOnly:
          type: boolean
          default: false
          description: >-
            When true, webhook payload only includes jobId and status (excludes
            output). Useful for large payloads.
          example: true
        model:
          type: string
          enum:
            - precision-2
          example: precision-2
          default: precision-2
          nullable: true
        numSpeakers:
          type: number
          minimum: 1
          description: >-
            Number of speakers. Only use if the number of speakers is known in
            advance. Number of speakers is detected automatically if not
            provided. Setting this value results in better overall diarization
            performance. In rare cases where we cannot honor this request (e.g.
            short files and large number of speakers), a warning will be added
            to the output. Equivalent to sending minSpeakers==maxSpeakers
          example: 2
        minSpeakers:
          type: number
          minimum: 1
          description: Minimum number of speakers (must be <= maxSpeakers if both are set)
          example: 1
        maxSpeakers:
          type: number
          minimum: 1
          description: Maximum number of speakers (must be >= minSpeakers if both are set)
          example: 4
        turnLevelConfidence:
          type: boolean
          nullable: true
          default: false
          description: Includes turn-level confidence values in the output.
          example: true
        exclusive:
          type: boolean
          default: false
          description: >-
            Includes exclusive diarization values in the output in
            `exclusiveDiarization` key (equivalent to diarization but without
            overlapping speech).
          example: true
        confidence:
          type: boolean
          default: false
          description: >-
            Include confidence values in the output. Output is considerably
            larger when this option is enabled. Output includes a list of
            confidence scores with a resolution.
          example: true
        matching:
          description: Customize how voiceprints are matched against speakers
          allOf:
            - $ref: '#/components/schemas/MatchingOptions'
        voiceprints:
          minItems: 1
          maxItems: 50
          description: List of voiceprints to identify against
          type: array
          items:
            $ref: '#/components/schemas/Voiceprint'
      required:
        - voiceprints
    JobCreated:
      type: object
      properties:
        jobId:
          type: string
          example: 3c8a89a5-dcc6-4edb-a75d-ffd64739674d
          description: ID of the job
        status:
          type: string
          description: Status of the job
          example: created
          enum:
            - pending
            - created
            - succeeded
            - canceled
            - failed
            - running
        warning:
          type: string
          description: Warning message if any
      required:
        - jobId
        - status
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Invalid request
        errors:
          description: List of errors
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      required:
        - message
        - errors
    ApiError:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
          example: 37a4c3a0-b034-4e8c-9ed9-76da6645544a
        message:
          type: string
          description: Error message
          example: Error message
      required:
        - requestId
        - message
    MatchingOptions:
      type: object
      properties:
        exclusive:
          type: boolean
          nullable: true
          default: true
          description: >-
            Prevent multiple speakers from being matched to the same voiceprint.
            Default to true
        threshold:
          type: number
          nullable: true
          default: 0
          minimum: 0
          maximum: 100
          format: float
          description: >-
            Prevent matching if confidence score is below this threshold. Value
            is between 0 and 100. Default is 0, meaning all voiceprints are
            matched
    Voiceprint:
      type: object
      properties:
        label:
          type: string
          maxLength: 100
          pattern: ^(?!speaker_).*
          description: Label for the speaker. Labels can't start with "SPEAKER_"
          example: John Doe
        voiceprint:
          type: string
          maxLength: 20000
          format: base64
          description: Voiceprint of a speaker
          example: U29tZUJhc2U2NERhdGE
      required:
        - label
        - voiceprint
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field name
          example: url
        message:
          type: string
          description: Error message
          example: Invalid URL
      required:
        - field
        - message
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http

````