> ## 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.
# PII/PHI Redaction Batch
> Transcribe a pre-recorded audio file and redact PII/PHI from both the transcript text and the returned audio.
## OpenAPI
````yaml api/velma_2_pii_phi_redaction_batch.yaml POST /api/velma-2-pii-phi-redaction-batch
openapi: 3.1.0
info:
title: Velma 2 PII/PHI Redaction Batch API
version: 0.0.0
description: >
Batch transcription and redaction of audio files via HTTP POST. Transcribes
the audio, identifies personally identifiable information (PII) and personal
health information (PHI) in the transcript, redacts the text, and silences
the
corresponding audio ranges. Optional speaker diarization adds a speaker
label
to each utterance.
## Response Format
The response is `multipart/form-data` with two parts: a `metadata` JSON part
(the redacted transcript, the utterances, and the redaction ranges applied
to
the audio) and an `audio` part (the redacted MP3 with the PII/PHI ranges
silenced).
servers:
- url: https://platform.modulate.ai
description: Modulate PII/PHI Redaction Batch Server
security:
- ApiKeyAuth: []
paths:
/api/velma-2-pii-phi-redaction-batch:
post:
summary: Transcribe and redact PII/PHI from an audio file
description: >
Transcribe an audio file, detect PII/PHI in the transcript, redact the
text, and
silence the corresponding audio ranges. Returns a multipart response
containing
redacted metadata (JSON) and redacted audio (MP3).
operationId: redactPiiPhiBatch
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- upload_file
properties:
upload_file:
type: string
format: binary
description: >
Audio file to transcribe and redact. Supported formats: AAC,
AIFF, FLAC, MP3, MP4, MOV, OGG, Opus, WAV, WebM.
Maximum file size: 100MB.
Empty files are rejected.
speaker_diarization:
type: boolean
default: true
description: >
Speaker diarization identifies different speakers in the
audio.
When enabled, each utterance includes a speaker identifier
(e.g., 1, 2).
start_redaction_padding_ms:
type: integer
default: 100
minimum: 0
description: >
Additional silence in milliseconds to prepend before each
redacted
audio range. Extends the silenced region earlier in time to
provide
a buffer before PII/PHI content.
end_redaction_padding_ms:
type: integer
default: 0
minimum: 0
description: >
Additional silence in milliseconds to append after each
redacted
audio range. Extends the silenced region later in time to
provide
a buffer after PII/PHI content.
language:
type: string
pattern: ^[A-Za-z]{2,3}([-_][A-Za-z0-9]+)*$
description: >
Optional language hint as a case-insensitive ISO 639-1 code
(e.g. "en", "fr"). BCP 47 region/script subtags (e.g.
"en-US")
are accepted; only the primary language subtag is used. When
omitted, the language is detected automatically for each
utterance.
responses:
'200':
description: Redaction completed successfully
content:
multipart/form-data:
schema:
type: object
properties:
metadata:
$ref: '#/components/schemas/RedactionMetadata'
audio:
type: string
format: binary
description: Redacted MP3 audio file with PII/PHI ranges silenced.
examples:
redacted:
summary: Redacted transcript with silenced audio ranges
value:
metadata:
text: Hello, my name is .
duration_ms: 5000
utterances:
- utterance_uuid: e5f6a7b8-c9d0-1234-efab-345678901234
text: Hello, my name is .
start_ms: 0
duration_ms: 3000
speaker: 1
language: en
redaction_ranges:
- - 1600
- 2400
audio: (binary MP3 data)
'400':
description: Bad request - Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_format:
summary: Invalid file format
value:
detail: >-
Unsupported file format. Supported formats: .aac, .aiff,
.flac, .mov, .mp3, .mp4, .ogg, .opus, .wav, .webm.
empty_file:
summary: Empty file
value:
detail: The uploaded file is empty.
invalid_language:
summary: Invalid language code
value:
detail: >-
Invalid language='english'. Expected an ISO 639-1 language
code (e.g. 'en', 'fr').
bad_value:
summary: Malformed request value
value:
detail: Invalid request.
'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 field is missing or
malformed (e.g. the API key header or the audio file)
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
examples:
missing_field:
summary: Required field missing
value:
detail:
- loc:
- header
- X-API-Key
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
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.
components:
schemas:
RedactionMetadata:
type: object
required:
- text
- duration_ms
- utterances
- redaction_ranges
properties:
text:
type: string
description: >
The complete redacted transcript from the audio file. Each detected
PII
or PHI span is replaced with an empty marker tag - `` for
health information and `` for personal
information, where CATEGORY identifies the detected entity type -
with
the surrounding text preserved.
example: Hello, my name is .
duration_ms:
type: integer
minimum: 0
description: >
The total duration of the processed audio in milliseconds. This
value represents
the actual audio duration and is used for usage tracking and billing
purposes.
example: 45000
utterances:
type: array
description: >
Array of individual utterances detected in the audio, ordered by
start time.
Each utterance contains the redacted text and timing information.
items:
$ref: '#/components/schemas/Utterance'
redaction_ranges:
type: array
description: >
List of time ranges (in milliseconds) that were silenced in the
returned
audio. Each range is a two-element array [start_ms, end_ms]. These
ranges
reflect the final merged and padded ranges applied to the audio.
items:
type: array
items:
type: integer
minItems: 2
maxItems: 2
example:
- - 1600
- 2400
- - 8000
- 9500
ErrorResponse:
type: object
required:
- detail
properties:
detail:
type: string
description: Human-readable error message describing what went wrong
example: >-
Unsupported file format. Supported formats: .aac, .aiff, .flac,
.mov, .mp3, .mp4, .ogg, .opus, .wav, .webm.
HTTPValidationError:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationError'
Utterance:
type: object
required:
- utterance_uuid
- text
- start_ms
- duration_ms
- speaker
- language
properties:
utterance_uuid:
type: string
format: uuid
description: Unique identifier for this utterance.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
text:
type: string
description: >
The redacted text for this utterance. Each detected PII or PHI span
is
replaced with an empty marker tag - `` for health
information
and `` for personal information, where
CATEGORY identifies the detected entity type - with the surrounding
text
preserved.
example: Hello, my name is .
start_ms:
type: integer
minimum: 0
description: >
The start time of this utterance in milliseconds, relative to the
beginning
of the audio file.
example: 0
duration_ms:
type: integer
minimum: 0
description: The duration of this utterance in milliseconds.
example: 2500
speaker:
type: integer
description: >
Speaker number for this utterance (1-indexed). When speaker
diarization is enabled,
this identifies which speaker produced this utterance. Speaker
numbers are consistent
within a single audio file but may vary between different files.
example: 1
language:
type: string
description: >
The automatically detected language code for this utterance (e.g.,
"en" for English,
"fr" for French).
example: en
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.
````