openapi: 3.1.0
info:
title: Velma 2 Accent Batch Velma 2 Pii Phi Redaction Batch API
version: 0.0.0
description: "Batch accent detection on an audio file via HTTP POST. Returns a single\nwhole-file accent label plus a time series of fixed-length windows, each\nwith its own accent label.\n\n## Behavior Notes\n- The `time_series` entries are consecutive, fixed-length windows over the\n file; each entry's `start_ms` and `duration_ms` delimit its span. A\n trailing remainder shorter than one full window is omitted.\n- A file shorter than one window returns an empty `time_series`; the\n whole-file `accent` is still returned.\n- `accent` is always a non-null string.\n"
servers:
- url: https://platform.modulate.ai
description: Modulate Accent Batch Server
security:
- ApiKeyAuth: []
tags:
- name: Velma 2 Pii Phi Redaction Batch
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 <pii:name></pii:name>.
duration_ms: 5000
utterances:
- utterance_uuid: e5f6a7b8-c9d0-1234-efab-345678901234
text: Hello, my name is <pii:name></pii:name>.
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.
tags:
- Velma 2 Pii Phi Redaction Batch
components:
schemas:
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 - `<phi></phi>` for health information
and `<pii:CATEGORY></pii:CATEGORY>` for personal information, where
CATEGORY identifies the detected entity type - with the surrounding text
preserved.
'
example: Hello, my name is <pii:name></pii:name>.
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
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 - `<phi></phi>` for
health information and `<pii:CATEGORY></pii:CATEGORY>` for personal
information, where CATEGORY identifies the detected entity type - with
the surrounding text preserved.
'
example: Hello, my name is <pii:name></pii:name>.
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
HTTPValidationError:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationError'
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.'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: API key used for authentication and usage tracking.