A supplier sends a voice note instead of completing a procurement form. The recording may mention a purchase-order number, a delivery date, or a request to correct an order. An integration can turn the recording into text, but a successful transcription does not prove that every number, date, or instruction was recognized correctly.
From recording to a reviewed procurement case
- Receive: identify the supplier recording in Object Storage and validate the request.
- Transcribe: OIC submits an OCI Speech job and tracks it to a terminal state.
- Retrieve: download the transcript JSON and reconcile each input file.
- Validate: check important identifiers against trusted procurement data; send uncertainty for review.
- Respond: optionally synthesize an acknowledgement from the confirmed case state.
A completed transcription is recognition output. Business authorization and approval remain separate workflow decisions.
This tutorial shows how to connect recorded audio, asynchronous speech recognition, transcript retrieval, deterministic business validation, and a spoken acknowledgement. It uses a fictional supplier voice-note-to-case workflow and explains the controls an experienced OIC developer must add before using the pattern for real business processing.
The examples use current public OCI Speech and Oracle Integration documentation as the reference baseline. No tenant, integration, job, transcript, or audio file has been executed for this article. Values and output samples marked illustrative are examples only.
1. What You Will Build
A supplier audio object is already stored in OCI Object Storage. OIC receives case metadata, submits a batch transcription job to OCI Speech, tracks its state, retrieves the transcript JSON, and validates important identifiers. After the case logic chooses an appropriate next step, the workflow can generate a spoken acknowledgement using Text-to-Speech (TTS).
Object Storage
Submit and track
Parse and validate
Review and respond
This tutorial includes two implementation paths: the native OCI Speech action in OIC and the corresponding OCI CLI/API route. It also explains transcript quality evaluation, diarization, the limits of vocabulary customization, optional OCI Language processing, and operational recovery.
Completion evidence: a recorded transcription-job OCID, a terminal job state, the actual JSON transcript artifact, an identifier-validation result, and—if TTS is used—a generated audio file that can be played or downloaded. These are target evidence items, not claims that this tutorial has executed them.
2. In This Post
- Shared setup, identity, endpoints, and example inputs
- Speech-to-text: submit, track, retrieve, and validate
- Transcript structure, diarization, evaluation, and customization
- Text-to-speech: synthesize and deliver an acknowledgement
- Combine Speech, business validation, privacy, Language, and translation
- Recovery, retention, and enterprise operations
- Completion checklist
- Five useful FAQs
- References
3. Before You Begin — Shared Setup
3.1 Understand which component does what
OCI Speech performs speech recognition or speech synthesis. OCI Object Storage holds the original media and, for batch transcription, the generated transcript artifacts. OIC coordinates the steps, maps data between operations, and routes the case according to deterministic business rules. A downstream procurement system remains the authority for order status, approval, and supplier permissions.
The native OIC Speech action documents Create, Get, List, Update, and Delete transcription-job operations, plus Synthesize Speech. The published action guide does not list task-level retrieval as a separate native action. Task inspection is available through the OCI Speech API/CLI, which is useful when a batch job contains multiple files or a partial result needs diagnosis.
Use the current OIC AI Feature Availability table and the OCI Speech overview to check your actual realm and region. Do not interpret documentation as proof that a particular tenant has the feature enabled.
3.2 Identity and Object Storage permissions
Authentication is different for the two paths. The native OIC action uses the OCI service-access identity configured for the Oracle Integration instance. A local OCI CLI command uses the identity and request-signing configuration of the active local OCI profile. Permission for a developer's CLI profile does not automatically grant permission to the OIC instance, and the reverse is also true.
| Identity or resource | What to verify |
|---|---|
| OIC service-access identity | Grant the Speech permissions and narrowly scoped Object Storage access required by the flow. For example, OIC may need to read the input object and read the generated transcript; the selected pattern may also need write access for an output or acknowledgement object. |
| Speech job and task APIs | Confirm permissions for creating, reading, listing, cancelling, or deleting the relevant Speech resources. Do not grant broad tenancy-wide access merely because it appears in an introductory example. |
| Object Storage access | Confirm the documented access needed to read source media and write transcript output. Speech permissions alone should not be assumed to grant object access. |
| Local OCI CLI profile | Verify the selected profile, tenancy/user or resource principal, region, signing configuration, compartment, and the needed Speech/Object Storage permissions. |
Native OIC identity setup: follow Oracle Integration AI prerequisites. The current procedure uses an identity-domain dynamic group whose matching rule identifies the OIC OAuth application client ID. Use that documented identifier; a Compute-instance matching rule or an integration-instance OCID is not an interchangeable substitute for this setup.
Oracle's About Speech Policies page describes Speech resource types and required permissions. Its broad policy examples help explain the resource family; adapt policies to the identities, compartments, buckets, and operations in your environment rather than copying a tenancy-wide policy blindly.
3.3 API version, endpoint, and request signing
The example API version is 20220101. It is the Speech API version, not an OIC release or model version. The Phoenix Speech endpoint is shown below. Check the OCI API Reference and Endpoints for the intended realm and region.
https://speech.aiservice.us-phoenix-1.oci.oraclecloud.com
Use the regional endpoint published by Oracle for the actual region and operation. Do not construct a hostname by changing a region suffix without checking the endpoint reference. OCI REST APIs use OCI request signing; a generic bearer-token header is not a substitute for signing when the operation requires OCI signed requests. The CLI examples below are signed CLI invocations, not literal HTTP requests.
3.4 Synthetic case fixture
Use the following fictional input for a lab. The expectedPurchaseOrderId must come from trusted case metadata or an authoritative procurement lookup—not from the transcript being validated. If the case does not already know the expected PO number, use the recognized number only as a candidate for an authoritative lookup. Confirm that the order belongs to the authenticated supplier and matches the case context; finding an existing order alone does not prove that the spoken number was recognized correctly. In the sample, en-IN requires media meeting the documented locale-specific sample-rate minimum (at least 16 kHz for Oracle ASR).
{
"caseId": "CASE-2026-0017",
"expectedPurchaseOrderId": "PO-10482",
"audioObject": {
"namespaceName": "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE",
"bucketName": "supplier-audio-in",
"objectName": "2026/10/supplier-042-note.wav"
},
"languageCode": "en-IN"
}
The object must already exist and be accessible to the selected path. This JSON is metadata; it does not contain the audio bytes. The sample assumes Indian English and a compatible audio file. Replace all placeholder values before execution.
Logging rule: correlate using case ID, job/task OCIDs, object keys, validation outcome, and OIC instance/run identifiers. Do not routinely log raw audio, complete transcripts, supplier secrets, or unnecessary personal information.
4. Speech-to-Text — Submit, Track, Retrieve, and Validate
4.1 Understand the asynchronous pattern
Speech-to-text, also called automatic speech recognition (ASR), converts recorded speech into text. In the batch API, a transcription job represents the overall request and a transcription task represents processing for an individual input file. The job ID is not the transcript text.
Kid-friendly analogy
Imagine giving a librarian a box of recordings. The librarian accepts the request, processes the recordings, and puts the finished pages on a shelf. A receipt for the request is not the finished pages.
In this OCI AI integration, this means: Track the job to a terminal state, then retrieve and inspect the output artifact from Object Storage instead of treating the initial job response as transcript text.
Oracle's current Speech overview lists AAC, AC3, AMR, AU, FLAC, M4A, MKV, MP3, MP4, OGA, OGG, OPUS, WAV, and WEBM as supported file formats. The documented maximum size is 2 GB per media file, the maximum duration is four hours, a job can contain up to 100 tasks, and jobs are retained for 90 days. These are service limits, not guarantees of completion time.
See OCI Speech Overview and Creating a Transcription Job for the current media/model requirements.
4.2 Choose model, language, and audio quality
File-extension acceptance does not prove that the audio is suitable. Check the actual encoding, sample rate, number of channels, duration, language, and background noise. A supported model cannot reconstruct words that are not audible.
OCI Speech documents an Oracle ASR model and Whisper-based models for recorded-media transcription. Oracle ASR is locale-specific; documented locales include en-US, en-GB, en-AU, en-IN, es-ES, pt-BR, hi-IN, fr-FR, de-DE, and it-IT. Whisper supports a wider language range and the documented language-identification option, using auto where supported. Model names and availability can change; select values from the current Console/API schema rather than copying an enum from an older SDK page.
| Decision | Practical guidance |
|---|---|
| Format and encoding | Use a documented format and inspect the actual encoding; a file named .wav is not proof that its encoding is valid or optimal. |
| Language/model | Choose a supported locale for Oracle ASR. Use Whisper language identification only when supported and validated for the selected model and operation. |
| Sample rate | Follow the chosen model/locale guidance. Oracle's overview recommends 8 kHz for low-fidelity media and 16–48 kHz for higher-fidelity media; check locale-specific requirements where applicable. |
| Size and duration | Validate the 2 GB and four-hour service limits before job creation. Any smaller application/OIC limit is an additional constraint, not an OCI Speech limit. |
| Noise and channels | Evaluate representative recordings. Test downmixing or preprocessing on a labeled sample before making it a production rule. |
4.3 Native OIC route — Create the transcription job
This route uses the native OCI Speech action; a separate Speech REST Adapter connection is not needed just to create a job.
- Create an OIC integration contract. For a lab, create a REST-triggered integration that accepts the case metadata from Section 3.4. Validate mandatory fields and restrict which buckets and object keys the caller can request.
- Add the Speech action. In the integration canvas, drag OCI Speech from Actions, or use the add icon at the intended point. Give the action a descriptive name such as
CreateSupplierTranscription. - Choose the operation. Select the Speech to text category and Create transcription job. Configure the compartment and output bucket in the action wizard. Oracle documents that supported mapper values can override the configured compartment or bucket at runtime.
- Map the request. Use the mapper generated by your tenant. Map the case-derived display name, description, language/model settings, punctuation and diarization choices, input location, and output namespace/bucket/prefix. The published action guide documents the top-level target elements, including
Location TypeandObject Locations; use the actual nested schema to map the namespace, bucket, and object name instead of guessing an XPath. - Save the job response. Capture the returned job OCID and initial lifecycle state into process variables such as
vTranscriptionJobIdandvJobState. Preserve the case ID in the same orchestration context. - Track the job with a bounded loop. Add Get transcription job and map
vTranscriptionJobIdto its Transcription Job Id input. Repeat while the job is in a nonterminal state, using an appropriate supported delay. Define a maximum number of checks or elapsed-time guard. Do not create a tight, infinite loop. - Handle all outcomes. Treat
SUCCEEDEDas job-level success, and handleFAILED,CANCELED, and timeout explicitly. If individual tasks have mixed outcomes, reconcile each input file; do not assumePARTIALLY_SUCCEEDEDis a documented job lifecycle value. - Retrieve the transcript object. Use the native Object Storage action to read the output from the configured bucket. Oracle Integration's current example documents an output-key convention based on the job ID and a name derived from the namespace, input bucket, and input object. Treat the configured prefix and the actual key as part of the contract, and verify the key with a real job before building a production expression around it. Nested object names and output prefixes must be tested rather than assumed.
- Parse the JSON artifact. Use Stage File's Read Entire File operation with a sample JSON schema generated from an actual output file. Map
transcriptions[].transcriptionto the text needed by the case process. Keep the raw JSON where policy permits, so later evaluation does not depend only on a flattened text field. - Verify the run. In OIC monitoring, correlate the case ID, execution, and Speech job ID. Confirm that the terminal state was handled, the output object exists, parsing succeeded, and the text reached validation.
Task-level caveat: the published native Speech action guide does not list Get Transcription Task as an OIC action. If a partial job requires per-task details, use the documented Speech API/CLI path for task inspection or route the case to an operational process that can inspect those details.
OIC orchestration boundary: A long-running job may outlast a synchronous REST request or the applicable integration execution limits. For production, prefer a durable state record and scheduled/event-driven status checks over holding a client connection open indefinitely. The tutorial describes configuration and validation steps, not a ready-to-import OIC integration package.
4.4 Direct API contract — Create a transcription job
The REST operation is POST /20220101/transcriptionJobs. The request includes a compartment, an input-location object, an output-location object, and model details. Bucket names and object names are nested values; they are not interchangeable with the OCI namespace or compartment ID.
{
"compartmentId": "REPLACE_WITH_COMPARTMENT_OCID",
"displayName": "CASE-2026-0017",
"description": "Synthetic supplier voice-note transcription",
"inputLocation": {
"locationType": "OBJECT_LIST_INLINE_INPUT_LOCATION",
"objectLocations": [
{
"namespaceName": "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE",
"bucketName": "supplier-audio-in",
"objectNames": ["2026/10/supplier-042-note.wav"]
}
]
},
"outputLocation": {
"namespaceName": "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE",
"bucketName": "supplier-audio-out",
"prefix": "speech-results"
},
"modelDetails": {
"modelType": "ORACLE",
"languageCode": "en-IN",
"transcriptionSettings": {
"diarization": { "isDiarizationEnabled": false }
}
}
}
This is an illustrative REST request body. Check the current API schema for required fields and supported enum values in your region. The choice ORACLE with language en-IN assumes the recording is Indian English and meets the selected model's media requirements. To request an additional SRT file, use the documented additionalTranscriptionFormats option with SRT, where supported. For precise required and optional fields, use the current OCI Speech API schema or generate an example JSON parameter with the installed CLI.
4.5 Execute the CLI route
The OCI CLI signs requests using its configured profile. Install and configure the CLI, validate the active profile and region, and confirm permissions before running these commands. The examples below use a POSIX-style shell such as Bash; adapt quoting and line continuation if you use PowerShell.
Create input-location.json:
{
"locationType": "OBJECT_LIST_INLINE_INPUT_LOCATION",
"objectLocations": [
{
"namespaceName": "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE",
"bucketName": "supplier-audio-in",
"objectNames": ["2026/10/supplier-042-note.wav"]
}
]
}
Create output-location.json:
{
"namespaceName": "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE",
"bucketName": "supplier-audio-out",
"prefix": "speech-results"
}
Create model-details.json:
{
"modelType": "ORACLE",
"languageCode": "en-IN",
"transcriptionSettings": {
"diarization": { "isDiarizationEnabled": false }
}
}
Submit the job:
oci speech transcription-job create \
--compartment-id "REPLACE_WITH_COMPARTMENT_OCID" \
--display-name "CASE-2026-0017" \
--input-location file://input-location.json \
--output-location file://output-location.json \
--model-details file://model-details.json \
--region "REPLACE_WITH_SPEECH_REGION"
The returned resource contains the job ID. Store that returned ID; do not reconstruct it from the display name. Add --additional-transcription-formats SRT only if you need SRT and the current CLI/service combination supports that option.
Get the job status:
oci speech transcription-job get \
--transcription-job-id "REPLACE_WITH_RETURNED_JOB_OCID" \
--region "REPLACE_WITH_SPEECH_REGION"
List tasks for the job:
oci speech transcription-task list \
--transcription-job-id "REPLACE_WITH_RETURNED_JOB_OCID" \
--all \
--region "REPLACE_WITH_SPEECH_REGION"
The --all option retrieves every page, which matters when reconciling a multi-file job. Then inspect each task requiring diagnosis using the task OCID returned by the list operation:
oci speech transcription-task get \
--transcription-job-id "REPLACE_WITH_RETURNED_JOB_OCID" \
--transcription-task-id "REPLACE_WITH_RETURNED_TASK_OCID" \
--region "REPLACE_WITH_SPEECH_REGION"
These are CLI commands, not raw HTTP requests. For direct REST, use the documented API operation and an OCI-supported signer. Consult the OCI CLI Create Transcription Job reference, List Transcription Tasks, and Get Transcription Task pages for the current parameters.
4.6 Lifecycle handling and output retrieval
A useful state-handling design follows the lifecycle values documented by the selected operation. In the published CLI create-job waiter, accepted states include ACCEPTED, IN_PROGRESS, CANCELING, CANCELED, FAILED, and SUCCEEDED. Do not treat PARTIALLY_SUCCEEDED as a confirmed job lifecycle enum without checking the current API response model; partial file outcomes must still be reconciled through tasks.
- Nonterminal:
ACCEPTED,IN_PROGRESS, orCANCELING; continue bounded tracking.CANCELINGmeans cancellation is underway, not finished. An unfamiliar state must trigger a controlled diagnostic/review path rather than be treated as success. - Successful job: retrieve the output artifact and validate the individual task results before using the text.
- Failed or cancelled job: record the failure and stop normal processing; route to retry or human review under a defined policy.
- Mixed task outcomes: reconcile individual tasks and input objects. Do not treat the overall job state as proof every file succeeded.
- Unknown submission outcome: a client timeout after create does not prove no job was created. Reconcile existing job/resource data before submitting a replacement to reduce duplicate work.
Oracle Integration's From Headset to ATP example documents the output artifact pattern as a job-ID folder and a filename derived from the namespace, input bucket, and input object, under the configured output prefix. Treat that as a documented pattern to verify, not a reason to assume a key without checking the actual object produced by your job.
CLI artifact retrieval: after reconciling the job and tasks, inspect the configured output prefix if the actual key is not yet known. Match the returned JSON object to the intended job and input file; do not select the first JSON file in a shared prefix. Copy the exact object key into the download command. These commands require Object Storage list/read permissions.
oci os object list \
--namespace "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE" \
--bucket-name "supplier-audio-out" \
--prefix "speech-results" \
--all \
--region "REPLACE_WITH_OUTPUT_BUCKET_REGION"
oci os object get \
--namespace "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE" \
--bucket-name "supplier-audio-out" \
--name "REPLACE_WITH_VERIFIED_TRANSCRIPT_OBJECT_KEY" \
--file "transcript.json" \
--region "REPLACE_WITH_OUTPUT_BUCKET_REGION"
The CLI uses the configured prefix as a name filter; it does not prove a file belongs to this case. See Object List and Object Get for the current parameters.
4.7 Transcript artifact shape
The transcript is a stored artifact. The following abbreviated example is illustrative and is not a substitute for the JSON generated by the current service/model. Use a real output artifact as the Stage File sample schema. The confidence values in this example are strings; do not assume that the actual service always serializes them as strings, or that every optional field is present.
{
"transcriptions": [
{
"transcription": "Please check purchase order PO-10482. The delivery is expected Friday.",
"confidence": "0.94",
"speakerCount": 1,
"tokens": [
{
"token": "PO-10482",
"startTime": "1.120s",
"endTime": "2.050s",
"confidence": "0.86",
"type": "WORD",
"speakerIndex": 0
}
]
}
],
"audioFormatDetails": {
"format": "wav"
}
}
The text, confidence values, token timing, and speaker metadata shown are invented example data. Actual properties can vary with model and API response version. Validate field presence and types in the real JSON before mapping them. A confidence score can help prioritize review but does not guarantee business correctness; a speaker index is not an identity assertion.
4.8 Speech-to-text tests and troubleshooting
| Case | Expected behavior | Evidence |
|---|---|---|
| Positive: valid recording and supported locale | Job reaches a terminal successful state and expected task output is available. | Job/task OCIDs, lifecycle state, output object, parsed JSON. |
| Boundary: media below the selected model/locale requirements | Preflight validation rejects it or Speech reports a task error; it is not silently treated as valid business text. | Media metadata and task diagnostic details. |
| Failure: input object missing or inaccessible | The failure is diagnosed at the object, authorization, or service layer. | Object key, IAM policy check, task failure details. |
| Boundary: file exceeds 2 GB or four hours | Reject before submission or use a tested preprocessing/splitting design. | Preflight check and media size/duration. |
| Misuse: job remains accepted/in progress | Continue bounded polling; do not parse a result that is not ready. | State transitions, poll count, timeout outcome. |
| Partial-success job | Inspect task results for each original object. | Task list and per-task output/failure details. |
Common failure layers are caller IAM, source object access, media compatibility, service processing, output object naming/permissions, and Stage File parsing. The OCI Speech troubleshooting guide provides service-specific checks. The tests above are a plan; mark them not executed until a run produces evidence.
5. Transcript Quality, Diarization, Evaluation, and Vocabulary
5.1 Text, tokens, timestamps, and confidence
The transcript text is the readable recognition result. Token-level elements can connect words to timestamps and, when provided, word confidence or speaker metadata. Use these fields as complementary evidence. If an order identifier appears uncertain, compare the relevant audio interval with the expected identifier and authoritative business data.
Kid-friendly analogy
A teacher can mark when a word was spoken and how certain the note-taking system seemed, but those marks do not prove that every name or number was recorded correctly.
In this OCI AI integration, this means: Confidence and timing help find where to review; deterministic checks against trusted data decide whether a critical field is acceptable.
5.2 Diarization separates voices; it does not identify people
Speaker diarization groups or segments transcript content by speaker. OCI Speech may emit a speaker count or speaker index when the selected model and configuration support diarization. These are technical labels, not verified supplier or employee identities. Never use a speaker index to authorize a purchase-order change or prove who gave an instruction.
Oracle documents that diarization increases task latency, which is why it is disabled by default in the job-creation guidance. Enable it only when speaker separation is useful. The native OIC action guide documents an Is Diarization Enabled mapping; if a speaker-count override is required, confirm that the actual action schema exposes it or use a supported API route.
5.3 Evaluate WER and critical fields separately
Confidence alone is not an evaluation strategy. Build a labeled test set with human-checked reference transcripts and recordings representative of the languages, accents, noise conditions, acronyms, amounts, dates, and identifiers expected in the workflow.
WER = (S + D + I) / N
S = substitutions; D = deletions; I = insertions; N = number of words in the reference transcript.
Word error rate (WER) measures text differences using the chosen tokenization and normalization rules. The formula requires a nonempty reference (N > 0); define a separate policy for empty references instead of dividing by zero. It is not a confidence score or business-risk score, and it can exceed 1 if insertions are numerous. An overall WER can also hide the fact that one critical purchase-order number was wrong.
For example, reference text PO 10482 ships Friday and recognized text PO 10428 ships Friday differ by one substitution under a simple four-word tokenization, giving WER = 1/4 = 25%. The operationally important result is that the purchase-order identifier is incorrect. Record exact-match checks for important fields separately from WER.
Beginner check: A transcript can have a low WER yet still have the wrong purchase-order number. Validate exact IDs against trusted case data; do not automatically “correct” a spoken number based on an assumed match without a review policy.
- Version and retain the reference transcripts and evaluation recordings.
- Document normalization rules before comparing outputs.
- Measure WER and exact-match/error rates for PO numbers, dates, quantities, and amounts separately.
- Review false acceptance and false rejection, not only average accuracy.
- Set human-review thresholds from observed data and business consequences, not from an arbitrary confidence value.
Do not normalize away digits or punctuation when doing so could hide a meaningful identifier difference. Every test reported as passed needs run evidence; otherwise mark it not executed.
5.4 Vocabulary customization boundaries
OCI Speech documents customization resources trained from an entity list or data in Object Storage. The current customization guide describes creating customizations for live transcription. It does not establish that a custom vocabulary can be applied to every asynchronous batch job or to every model. The native OIC batch mapper also does not establish a general custom-vocabulary override.
Do not add a customization resource to this batch design unless the selected model, operation, and current API contract explicitly support it. If domain vocabulary is a major accuracy issue, evaluate the documented customization path separately and compare it with the baseline using the same labeled recordings. See Creating a Customization and Speech model comparison.
6. Text-to-Speech — Synthesize and Deliver an Acknowledgement
6.1 Understand the output contract
Text-to-Speech turns text into audio. The API call is synchronous: the response contains audio data for output formats such as MP3, PCM, or OGG. JSON output is a separate mode for speech-mark data. Do not treat audio bytes or a stream reference as if they were a JSON transcript.
The service supports a maximum of 10,000 characters per request. Natural and standard voices, locales, output formats, streaming, and SSML support vary by combination; check the current TTS language and feature support table before choosing one.
Kid-friendly analogy
Imagine writing an announcement before asking a loudspeaker to read it aloud. The wording must be decided first, and the sound still has to reach the people who need it.
In this OCI AI integration, this means: Generate an acknowledgement from validated business state, request a supported voice and format, then download or store the returned audio before presenting it as a file.
6.2 Native OIC route — Synthesize Speech
Use this route only when the native action is available to the OIC instance and the relevant Speech region supports TTS.
- Construct validated text. Use an application-controlled template such as the following. Use the case reference from trusted case metadata, not directly from untrusted transcript text.
We have received your voice note for case CASE-2026-0017. The procurement team will review the details and follow up. No purchase-order change has been made yet.
- Add and configure the action. Add OCI Speech, choose Text to speech, then Synthesize Speech. Set the configured Speech compartment and choose a supported predefined speaker.
- Map the request using the generated mapper schema. The published OIC guide lists these synthesis fields: Config Type, Compartment Id, Model Family, Model Name, Voice Id, Output Format, Sample Rate In Hz, Speech Mark Types, Text Type, Is Stream Enabled, and Text. Map the fields exposed by the current action schema, and use a documented supported value for each. For an ordinary acknowledgement, plain text is usually sufficient; speech-mark types are relevant when the output mode needs them.
- Handle the stream reference. Oracle says the action returns a stream reference that can be downloaded. A reference is not the audio bytes and is not proof that a persistent file exists. Follow the actual output contract exposed by the action, download the stream using a supported path, and then pass the binary content to a supported file or Object Storage operation.
- Verify the output. Confirm the download succeeds, the response has nonzero content, the file can be played, and the spoken acknowledgement says only what the business process has actually confirmed.
Implementation boundary: the public OIC guide documents the stream-reference behavior but does not give one universal mapper XPath or a universal persistence configuration for every action schema. Do not invent a field name or assume a stream reference is directly interchangeable with a binary file, Base64 string, or Object Storage object ID. Inspect the generated output schema in your tenant before implementing the transfer.
Regional deployment check: the CLI example below explicitly targets Phoenix. Selecting an OIC compartment does not select a different service region. For an OIC instance outside Phoenix, confirm a supported way to invoke Phoenix TTS and review any cross-region data movement before treating the native action as usable for this step.
6.3 CLI route — Generate an MP3 file
The CLI's current documented required inputs are the text and the destination file. The configuration below selects the Oracle model family, a natural English-US voice, MP3 output, and a 24,000 Hz sample rate. To customize voice/model/output settings, use the CLI's configuration parameter and check its schema against the current CLI reference. The following configuration shape corresponds to the documented Oracle-family TTS configuration; verify the desired voice/locale combination before execution.
Create tts-configuration.json:
{
"modelFamily": "ORACLE",
"modelDetails": {
"modelName": "TTS_2_NATURAL",
"voiceId": "Brian",
"languageCode": "en-US"
},
"speechSettings": {
"outputFormat": "MP3",
"sampleRateInHz": 24000,
"textType": "TEXT"
}
}
Run in a POSIX-style shell after configuring the OCI CLI profile:
oci speech synthesize-speech \
--text "We have received your voice note for case CASE-2026-0017. The procurement team will review the details and follow up. No purchase-order change has been made yet." \
--file acknowledgement.mp3 \
--configuration file://tts-configuration.json \
--compartment-id "REPLACE_WITH_COMPARTMENT_OCID" \
--region "us-phoenix-1"
The CLI writes the response data to acknowledgement.mp3. This command has not been executed for this article. If the selected voice, model, or settings are unsupported in your current CLI/service combination, use the generated CLI parameter schema and current TTS support table to correct the configuration. The official synthesize-speech CLI reference lists the current parameters.
The REST operation is POST /20220101/actions/synthesizeSpeech. The request body is JSON, but the normal MP3/PCM/OGG response is audio content; it must be handled as bytes. The API also supports a configuration and an optional audio-response configuration. For a direct REST client, use the current OCI Speech SDK/API reference and an OCI request signer instead of assuming an ordinary bearer header is sufficient.
6.4 Output format, sample rate, and SSML
Choose an output format according to the consumer. MP3 is convenient for downloadable voice messages; PCM or OGG may suit other playback paths. JSON is used when speech-mark data is needed and is not a normal audio-file substitute. The Console guide documents a sample-rate range from 8,000 to 48,000 Hz, but the selected voice and consumer still matter; verify the generated file rather than relying only on the requested setting.
Speech Synthesis Markup Language (SSML) can control pauses and pronunciation for supported voices. Oracle documents SSML support only for certain English US speakers, not for speakers in other listed languages. Use SSML as the input text type only when the selected voice supports it. For ordinary text, use TEXT.
<speak>
Your case number is
<say-as interpret-as="digits">20261017</say-as>.
</speak>
This SSML example is illustrative. Test the actual spoken pronunciation; a syntactically valid SSML document does not guarantee that every identifier will be spoken in the preferred business style.
6.5 Store and verify the audio
After synthesis, upload the generated file to Object Storage only if the workflow needs a persistent artifact. Use an application-controlled key based on the validated case identifier and a fixed filename. Confirm the bucket region, upload permissions, and the CLI version's parameters.
oci os object put \
--namespace "REPLACE_WITH_OBJECT_STORAGE_NAMESPACE" \
--bucket-name "supplier-acknowledgements" \
--name "CASE-2026-0017/acknowledgement.mp3" \
--file "acknowledgement.mp3" \
--content-type "audio/mpeg" \
--region "us-phoenix-1"
For an OIC route, verify that the native stream reference has been downloaded through the generated action response contract before attempting the upload. Do not use a stream reference as if it were the audio file itself.
| Test | Expected result | Evidence |
|---|---|---|
| Positive: supported text/voice/format | An audio response is written and can be played. | Command/action response, file size, detected format, playback. |
| Boundary: text over 10,000 characters | Reject preflight or split using a defined safe strategy. | Character count and observed response. |
| Failure: unsupported voice/format combination | Report a configuration/compatibility failure; do not assume the service silently changes voices. | Error, requested voice/model/format, current support table. |
| Misuse: stream reference treated as an MP3 | Do not publish a download link until the returned stream has been retrieved and checked. | Nonzero file, content format, successful playback. |
7. Combine Speech, Business Validation, Privacy, and Translation
7.1 End-to-end sequence
- Accept the request. Validate case ID, source object, approved language/model choice, and any expected identifiers supplied by trusted case metadata.
- Create and track the job. Use the native OIC action or the direct API/CLI route. Persist the job ID and correlate it with the case.
- Reconcile the terminal state. Handle success, failure, cancellation, partial success, and timeout explicitly.
- Retrieve and parse the output. Read transcript JSON from Object Storage and preserve the raw artifact according to the approved retention policy.
- Validate critical values. Check the PO number, date, quantity, and other important fields against expected case metadata or authoritative procurement data. Route mismatches and ambiguity for human review.
- Apply privacy controls when required. Distinguish sensitive-data detection from the application-controlled replacement or masking step.
- Build acknowledgement text from trusted state. State what has actually happened. Do not say that an order change was approved or completed unless the trusted business system confirms it.
- Optionally synthesize audio. Use a supported model/voice/format and verify the resulting audio before delivering it.
- Record the outcome. Store case ID, source key, job/task identifiers as available, transcript location, validation status, review outcome, acknowledgement location, and execution correlation.
Safety control
A transcript is untrusted input. It can contain recognition errors or wording that appears to request bypassing a control. Never allow transcript text or a model-derived interpretation to override authorization, procurement approval, idempotency, or the trusted target system.
7.2 OCI Language and privacy are separate steps
OCI Language can perform supported text operations such as language detection, entity recognition, classification, sentiment analysis, translation, and PII detection. The native OIC Language action has its own operations and mapper contract; do not reuse the Speech payload schema for it.
Important privacy distinction: detection locates supported sensitive values; transformation changes what is returned or shared. The native OIC Language action supports optional MASK, REPLACE, and REMOVE configurations, so a separate custom masking component is not always required. Configure the required transformation in the Language action or request, then map the resulting sanitized text deliberately. OCI Language can return maskedText alongside entity metadata containing original sensitive values; forwarding the whole response can therefore expose data even when the visible text is masked.
- Restrict access to the raw transcript and retain it only for an approved purpose and period.
- Invoke the documented Language operation for the required analysis/detection task, if available for the instance and region.
- Configure and test the Language action's masking/replacement/removal policy when transformed text is required. If a custom transformation is needed instead, account for offsets, text encoding, and changes to preceding spans.
- Check all downstream fields and logs; a redacted visible text field does not prove that sensitive values were removed from retained raw fields or metadata.
- Keep raw and transformed artifacts clearly distinguished, with separate access and retention rules.
Detection can miss sensitive content and transformation can be implemented incorrectly. Neither alone guarantees anonymization or regulatory compliance. For the service's transformed-text and entity-metadata contract, see OCI Language PII documentation. See Oracle's OIC OCI Language action guide and verify the exact operation contract before implementation.
7.3 Translation is not implicit in transcription
Speech recognition, language identification, and translation are distinct operations. If an acknowledgement must be in another language, explicitly translate the validated text using a supported OCI Language operation or another approved service. Then synthesize using a TTS voice supported for the target language and region.
Keep source and translated text separate. Validate that the translation preserves identifiers, names, dates, quantities, and the difference between a request received and a change approved. Do not assume an ASR language is supported by TTS, or that SSML support is the same across languages.
7.4 Combined-workflow verification
| Case | Expected behavior | Evidence |
|---|---|---|
| Positive: transcript matches expected PO | Store validated text and prepare an acknowledgement that reports receipt and next steps. | Transcript, validation result, case state, audio location if generated. |
| Boundary: recognized PO differs from trusted value | Route for review; do not execute an unauthorized purchase-order change. | Exact-match result, review state, audit record. |
| Failure: job succeeds but output retrieval fails | Record the failed retrieval and retry only under a bounded policy. | Job ID, expected key, object permission/error, retry decision. |
| Misuse: transcript requests an approval bypass | Treat it as input text; preserve normal authorization and approval checks. | Trusted workflow decision and target-system approval state. |
8. Enterprise Operations — Recovery, Retention, and Architecture
8.1 Batch versus live transcription
Batch transcription suits recordings that already exist and can be processed asynchronously. Live transcription is a different architecture with real-time session and streaming concerns. Do not treat a batch job as a real-time streaming channel. OCI Speech currently documents up to 10 concurrent Live Transcribe sessions per tenancy, with a limit increase possible through Oracle Support; that is a live-session limit, not the number of batch jobs. Check current quota and regional support before choosing an architecture.
8.2 Retry safely and reconcile uncertain outcomes
A network timeout after job submission does not prove that the service failed to create the job. Blindly resubmitting can create multiple jobs for the same recording. Maintain an application control record that relates the case ID and source object to the job ID, submission outcome, status, and artifact location. Reconcile known resources before attempting a replacement job.
API/SDK retry control: CreateTranscriptionJob supports opc-retry-token. Persist and reuse the same token when retrying the same logical create request through an API/SDK path that exposes it. Tokens normally expire after 24 hours and can be invalidated earlier by conflicting operations. This does not replace case-level deduplication. Do not invent a CLI switch or native-action mapper field if the installed client/action does not expose the token. See the Speech SDK client reference.
For multi-file jobs, reconcile individual tasks whenever partial success is possible. Oracle's Speech notifications example describes completion and failure notifications and notes that the completion event can also fire for partially successful jobs. Events can reduce polling, but they do not remove the need to inspect job/task outcomes and required artifacts.
8.3 Retention and cleanup
The Speech overview documents 90-day job retention; the SDK describes job availability as a maximum of 90 days. Do not depend on the job resource as a permanent audit archive. That does not automatically define the lifecycle of input recordings, output transcript files, or generated acknowledgement audio in Object Storage.
- Speech job: delete only when the current service permits deletion for its lifecycle state.
- Input recording: retain or delete under the approved business, privacy, and legal policy.
- Transcript JSON/SRT: manage separately with Object Storage lifecycle and access policies; preserve evidence needed for review.
- Acknowledgement audio: apply the case's retention rule and prevent unintended public access.
Oracle explicitly documents that deleting an OIC Speech transcription job does not delete the output transcript object in Object Storage. Do not treat job deletion as deletion of all derived data or as a complete privacy-erasure procedure.
8.4 Measure operations and cost drivers
Media duration/size, model, language, diarization, retries, and downstream work can affect processing time and total operating cost. Measure the workload rather than assuming a fixed completion time. Useful application-defined metrics include:
- Job acceptance-to-terminal latency and task success/failure counts.
- Transcript retrieval and parsing failure rate.
- Reference-based WER and critical-identifier error/review rate.
- TTS invocation and file-delivery failures, including playback checks.
- Duplicate-job reconciliation events and Object Storage cleanup outcomes.
These are suggested application metrics; do not assume OCI Speech supplies all of them as ready-made measurements. Keep retries bounded, logs privacy-aware, and retention explicit.
9. Completion Checklist
Use this list for a controlled lab completion record:
- Permissions are confirmed for the actual OIC identity or local CLI profile and the required buckets.
- The media format, encoding, language/model, size, duration, and sample rate are within documented constraints.
- The native OIC action or CLI/API route creates a job that can be tracked to a terminal outcome.
- The transcript artifact is retrieved and parsed using a schema based on actual output.
- Critical identifiers are validated against trusted metadata or the authoritative procurement system.
- WER and critical-field error rates are defined for a labeled evaluation set.
- PII detection and the configured transformation are both verified; downstream fields exclude raw sensitive entity values.
- The acknowledgement uses controlled text and a supported model/voice/format combination.
- The TTS result is downloaded/stored and verified as playable audio.
- Failure, timeout, uncertain submission, partial processing, and cleanup scenarios have observable expected outcomes.
- Only tests backed by execution evidence are marked passed; all others remain not executed.
A useful next exercise is to connect a validated transcript to an authoritative procurement case record and prove that a PO mismatch routes for review. That exercise should extend the traceability and deterministic validation already described here rather than hide missing Speech setup behind a future capstone.
10. Five Useful FAQs
1. Does a successful job response contain the completed transcript?
Not as a substitute for retrieving the result artifact. The job is an asynchronous resource; retrieve the output from Object Storage and inspect its content. Keep the job and task data correlated with the original object.
2. Does diarization prove who is speaking?
No. Speaker labels help separate turns but are not verified identities and must not be used as authorization evidence.
3. Can I use the same locale configuration for Speech-to-Text and Text-to-Speech?
Do not assume so. ASR model/locale support and TTS voice/locale/output support are separate contracts. Verify each selected combination independently. Current OCI Speech documentation lists TTS only in Phoenix.
4. Does a high confidence score prove that a PO number is correct?
No. Confidence is model-provided evidence, not business certainty. Use labeled evaluation and validate critical identifiers against trusted input or an authoritative business system.
5. Does deleting the Speech job delete its input and output objects?
No. Job deletion does not delete the transcript object from Object Storage. Manage the job, source media, transcript, and acknowledgement audio under separate lifecycle and retention policies.
11. References
Verification scope (31 October 2026): This review compared the technical claims, request examples, and CLI options with Oracle documentation. All 17 original Oracle reference URLs returned relevant content through the browsing service. Both original image URLs returned PNG content, but the illustration contained garbled text and was replaced with an editable HTML workflow. Ordinary direct requests to Oracle pages from this review environment returned an access-unavailable page, so HTTP 200 alone was not treated as evidence of a working reference. Internal anchors, HTML nesting, embedded JSON, and shell syntax were checked locally. No OCI jobs, OIC integrations, tenant IAM policies, audio playback, or production deployment were executed. Region, voice, and model support must still be confirmed for the target environment.
These official Oracle sources were checked for the product contracts and constraints described above. Some CLI/SDK references can expose a newer or older view of individual schema elements than the current Console guide; when they differ, verify the current operation schema and the actual region before production use.
- Oracle Integration 3 — Transcribe Speech to Text and Synthesize Text to Speech with a Speech Action. Native action operations, mapper fields, and stream-reference behavior.
- Oracle Integration 3 — AI Feature Availability. OCI AI action realm and regional support.
- OCI Speech — Speech Overview. Supported media types, limits, job retention, model comparison, and the TTS region note.
- OCI Speech — Creating a Transcription Job. Model, language, diarization, and SRT settings.
- OCI CLI — Create Transcription Job. Current CLI parameters and complex JSON inputs.
- OCI CLI — List Transcription Tasks and Get Transcription Task. Task-level reconciliation.
- OCI CLI — Synthesize Speech. TTS CLI parameters and output file behavior.
- OCI Speech — Using Text to Speech and Generating Text to Speech Output. Supported voices, formats, sample rates, and SSML constraints.
- OCI Speech — About Speech Policies. Resource types and IAM permissions.
- OCI Speech — Creating a Customization. Customization scope and training-data options.
- OCI Speech — Troubleshooting. Service-level diagnostic guidance.
- OCI Speech Go SDK reference. Request/response models for Speech operations.
- Oracle Integration 3 — Perform Text Analysis and Translation with a Language Action. Native OCI Language action support.
- Oracle Integration — From Headset to ATP: How OIC Turns Support Calls into Searchable Knowledge. Current example pattern for job tracking, transcript-key derivation, Object Storage retrieval, and Stage File parsing.
- Oracle Integration 3 — OCI AI prerequisites. Native-action identity-domain dynamic-group setup.
- OCI API Reference and Endpoints. Speech service endpoints and REST operations.
- Speech SDK — CreateTranscriptionJobDetails. Create-request fields.
- Speech SDK — TranscriptionModelDetails. Oracle and Whisper language/model settings.
- Speech SDK — TranscriptionJob. Lifecycle states, task counters, and retention.
- Speech SDK — TtsOracleConfiguration. Oracle-family TTS configuration.
- Speech SDK — Natural TTS model details. Voice and language fields.
- Speech SDK — TtsOracleSpeechSettings. Output format, sample rate, and text type.
- Speech SDK — Client reference. Create-request retry-token semantics.
- OCI Language — PII detection and transformation. Masked text and original entity metadata.
- OCI CLI — Object List. Prefix filtering and pagination.
- OCI CLI — Object Get. Transcript-file download.
- OCI CLI — Object Put. Audio upload and content-type metadata.
- Oracle AI & Data Science — Enabling Notifications for OCI Speech. Completion and failure notification example.
12. Finally — Summary
OCI Speech becomes useful in enterprise integration when its outputs are treated as evidence inside a controlled workflow, not as unquestioned business facts. For batch speech-to-text, validate the recording, create and track the asynchronous job, retrieve the output artifact, parse the transcript, and reconcile task-level outcomes whenever partial processing is possible. A job identifier and a transcript are different things, and successful processing does not guarantee correct purchase-order numbers, dates, or quantities.
Evaluate recognition against human-checked reference transcripts and test critical fields separately. Use diarization for speaker separation, not identity verification, and confirm customization support before designing around it. For TTS, verify regional availability, voice/model compatibility, output settings, and file handling; a stream reference is not a persisted audio file.
The essential engineering principle is traceability: preserve the link between the original recording, job/task, transcript, validation decision, case, and acknowledgement. Keep retries bounded, separate PII detection from transformation, and leave authorization and procurement approval in trusted application and business systems.
Comments
Post a Comment