> ## Documentation Index > Fetch the complete documentation index at: https://docs.modulate.ai/llms.txt > Use this file to discover all available pages before exploring further. # AI Music Detection Batch > Detect AI-generated music in an audio file. Returns a clip-level verdict plus a per-window breakdown of vocal and instrumental AI content. ## OpenAPI ````yaml api/velma_2_ai_music_detection_batch.yaml POST /api/velma-2-ai-music-detection-batch openapi: 3.1.0 info: title: Velma 2 AI Music Detection Batch API description: > Batch endpoint for detecting AI-generated music in audio files via HTTP POST. The clip is analysed as a sequence of windows, each classified by its vocal and instrumental content, and the per-window results are aggregated into a clip-level verdict. ## Performance Notes - Per-window results may be lower accuracy than the clip-level verdict and its confidence. Rely on the clip-level result when making a determination about an entire uploaded song or song segment. - Heavily processed or high-production songs may be incorrectly labeled as AI-generated; this is a known gap targeted by future updates to this model. version: 1.0.0 servers: - url: https://platform.modulate.ai description: Modulate AI Music Detection Batch Server security: - ApiKeyAuth: [] paths: /api/velma-2-ai-music-detection-batch: post: summary: Detect AI-generated music in an audio file description: | Accepts an audio file and returns a clip-level verdict on whether the content contains AI-generated music, along with a per-window breakdown of how each segment was classified. operationId: detectAIMusic requestBody: required: true content: multipart/form-data: schema: type: object required: - upload_file properties: upload_file: type: string format: binary description: | Audio file to analyse. Must be non-empty. Supported formats: `.aac`, `.flac`, `.m4a`, `.mp3`, `.mp4`, `.ogg`, `.opus`, `.wav`. Maximum file size: 100 MB. responses: '200': description: Detection completed successfully. content: application/json: schema: $ref: '#/components/schemas/AIMusicDetectionResponse' example: filename: my_audio.mp3 duration_s: 89.28 primary_verdict: ai-vocal-music vocal_percentage: 87.5 vocal_ai_percentage: 56.5 vocal_ai_confidence: 0.96 instrumental_percentage: 64.3 instrumental_ai_percentage: 10.5 instrumental_ai_confidence: 0.95 silence_percentage: 3.51 windows: - start_time_ms: 0 end_time_ms: 4000 vocal_percentage: 100 vocal_ai_percentage: 100 vocal_ai_confidence: 0.97 instrumental_percentage: 79 instrumental_ai_percentage: 0 instrumental_ai_confidence: 0 silence_percentage: 0 - start_time_ms: 4000 end_time_ms: 8000 vocal_percentage: 0 vocal_ai_percentage: 0 vocal_ai_confidence: 0 instrumental_percentage: 82 instrumental_ai_percentage: 0 instrumental_ai_confidence: 0.76 silence_percentage: 18 latency_ms: 1333 '400': description: > Bad request - the uploaded file is empty or its format is not supported. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: The uploaded file is empty. '403': description: Forbidden - the request is not permitted. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: This request is not permitted. '422': description: > Unprocessable entity - a required request parameter is missing or invalid. A missing `X-API-Key` header returns an `ErrorResponse` with detail "Invalid request."; a missing or invalid `upload_file` field returns the framework validation body. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/HTTPValidationError' examples: missing_api_key: value: detail: Invalid request. invalid_upload_file: value: detail: - loc: - body - upload_file msg: Field required type: missing '429': description: >- Too many requests - the request could not be completed due to insufficient credits. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Insufficient credits. '500': description: Internal server error during processing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Internal server error '502': description: Bad gateway - the request could not be validated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Unable to validate request. Please try again. security: - ApiKeyAuth: [] components: schemas: AIMusicDetectionResponse: type: object required: - filename - duration_s - primary_verdict - vocal_percentage - vocal_ai_percentage - vocal_ai_confidence - instrumental_percentage - instrumental_ai_percentage - instrumental_ai_confidence - silence_percentage - windows - latency_ms properties: filename: type: string description: > Name of the submitted audio file. Empty string if no filename was provided in the upload. example: my_audio.mp3 duration_s: type: number format: double minimum: 0 description: Total duration of the analysed audio in seconds. example: 89.28 primary_verdict: type: string enum: - ai-vocal-music - ai-instrumental - not-ai-music description: | Clip-level classification: - `ai-vocal-music` - AI-generated music with a detected synthetic voice (covers AI songs and AI synthetic vocal tracks). - `ai-instrumental` - AI-generated instrumental music with no detectable synthetic voice. - `not-ai-music` - the clip does not appear to contain AI-generated music. example: ai-vocal-music vocal_percentage: type: number format: double minimum: 0 maximum: 100 description: > Clip-level average percentage of the audio that contains vocal content, averaged across all windows. example: 87.5 vocal_ai_percentage: type: number format: double minimum: 0 maximum: 100 description: > Percentage of the clip duration classified as AI-generated vocals. Computed as (seconds of windows classified as AI vocals) / (total clip seconds) * 100. A window contributes its full duration when it is classified as AI-generated vocals; zero otherwise. example: 56.5 vocal_ai_confidence: type: number format: double minimum: 0 maximum: 1 description: > Average confidence that the vocal windows contain AI-generated vocals, across all windows with vocal content. Not diluted by non-vocal windows. example: 0.89 instrumental_percentage: type: number format: double minimum: 0 maximum: 100 description: > Clip-level average percentage of the audio that contains instrumental music content, averaged across all windows. example: 64.3 instrumental_ai_percentage: type: number format: double minimum: 0 maximum: 100 description: > Percentage of non-vocal non-silent windows classified as AI-generated instrumental content (0-100 scale). example: 10.5 instrumental_ai_confidence: type: number format: double minimum: 0 maximum: 1 description: > Maximum confidence that a non-vocal window contains AI-generated instrumental content. Zero if no such window was found. example: 0.95 silence_percentage: type: number format: double minimum: 0 maximum: 100 description: > Clip-level average percentage of the audio that contains neither vocal nor instrumental content, averaged across all windows. example: 3.51 windows: type: array items: $ref: '#/components/schemas/WindowPrediction' description: Per-window breakdown of detection results. latency_ms: type: number format: double minimum: 0 description: End-to-end inference time in milliseconds. example: 1333 ErrorResponse: type: object required: - detail properties: detail: type: string description: Human-readable error message. HTTPValidationError: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationError' WindowPrediction: type: object required: - start_time_ms - end_time_ms - vocal_percentage - vocal_ai_percentage - vocal_ai_confidence - instrumental_percentage - instrumental_ai_percentage - instrumental_ai_confidence - silence_percentage properties: start_time_ms: type: integer minimum: 0 description: Window start time in milliseconds. example: 0 end_time_ms: type: integer minimum: 0 description: Window end time in milliseconds. example: 4000 vocal_percentage: type: number format: double minimum: 0 maximum: 100 description: | Percentage of this window that contains vocal content. example: 100 vocal_ai_percentage: type: number format: double minimum: 0 maximum: 100 description: > `100` if this window is classified as containing AI-generated vocals; `0` otherwise. Only meaningful for vocal windows; always `0` for windows without sufficient vocal content. example: 100 vocal_ai_confidence: type: number format: double minimum: 0 maximum: 1 description: > Confidence that this window contains AI-generated vocals. Present only for vocal windows; `0` for windows without sufficient vocal content. example: 0.97 instrumental_percentage: type: number format: double minimum: 0 maximum: 100 description: | Percentage of this window that contains instrumental music content. example: 79 instrumental_ai_percentage: type: number format: double minimum: 0 maximum: 100 description: > `100` if this window is classified as AI-generated instrumental content; `0` otherwise. Only meaningful for non-vocal windows; always `0` for vocal windows. example: 0 instrumental_ai_confidence: type: number format: double minimum: 0 maximum: 1 description: > Confidence that this window contains AI-generated instrumental content. Present only for non-vocal windows; `0` for vocal windows. example: 0 silence_percentage: type: number format: double minimum: 0 maximum: 100 description: > Percentage of this window that contains neither vocal nor instrumental content. example: 0 ValidationError: type: object required: - loc - msg - type properties: loc: type: array items: anyOf: - type: string - type: integer msg: type: string type: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key used for authentication and usage tracking. ````