Create a transcription

Submit an uploaded file or a public media URL, quote and reserve Characters, and start the task.

POST /sound_clone/api/v1/stt/transcriptions

Create a transcription

cURL

curl --request POST \
  --url https://api.myvocal.ai/sound_clone/api/v1/stt/transcriptions \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'accessKey: <accesskey>' \
  --data '
{
  "uploadId": "<string>",
  "mediaUrl": "<string>",
  "audioTrackIndex": 123,
  "languageHint": "<string>",
  "title": "<string>",
  "modelId": "<string>",
  "options": {},
  "waitForCompletion": true,
  "waitTimeoutMs": 123
}
'

200

{
  "code": 123,
  "message": "<string>",
  "data": {
    "transcriptionId": "<string>",
    "requestId": "<string>",
    "status": "<string>",
    "modelId": "<string>",
    "billing": {}
  }
}

_{Speech to Text · Batch · Workflow: Batch quickstart}

Submits one transcription from an uploadId or a public mediaUrl. The call quotes the work, reserves Characters and starts the asynchronous task in a single request.

Header

accessKey · string · required

Your API key. See Authentication.

Idempotency-Key · string · required

Binds this request. The same key and the same body return the same task; the same key with a different body is refused as IDEMPOTENCY_CONFLICT.

Body

uploadId · string

An upload from POST /uploads. Use exactly one of uploadId or mediaUrl.

mediaUrl · string

A public http/https URL. The server fetches it over a real connection and re-checks every redirect; private, loopback, link-local and cloud-metadata addresses are refused. There is no domain or port allowlist. A failure reports details.reason (DESTINATION_NOT_ALLOWED, SOURCE_REFUSED, SOURCE_UNAVAILABLE, SOURCE_UNREACHABLE, TOO_MANY_REDIRECTS or UNSUPPORTED_TYPE) and, when the host answered, details.sourceStatus; see public media URLs.

audioTrackIndex · number

Which audio track to transcribe. Required when the source contains more than one audio track; use the index from the upload’s media.audioTracks.

languageHint · string

The spoken language, or omit for automatic detection. The hint is echoed as languageHint; it is never reported as the detected language.

title · string

A title for the History row.

modelId · string

Optional model identifier; defaults to myvocal_stt_v1.

options · object

Processing options: separateSpeakers, maxSpeakerCount, alignmentLevel, entityCategories, redactCategories, redactionStyle, rewriteInstruction, removeDisfluencies, identifyConversationRoles, vocabularyHints, separateChannels, channelResultMode, exportFormats, inputEncoding, processingContentStorage and more. Option combinations that the model does not support are refused at submit with INPUT_INVALID rather than silently dropped. Completion notifications are options too: options.notifyOnCompletion (true to enable), options.notifyUrl (a public URL MyVocal posts the signed event to), options.clientMetadata (opaque caller data echoed back) and options.notificationSigningSecret (the write-only HMAC key). Polling stays the authoritative result. See capabilities for the live list.

waitForCompletion · boolean

When true, this call waits for a terminal state inside the same request.

waitTimeoutMs · number

The wait budget in milliseconds. If the task is still running at the budget, the request returns the task with its identity; it is not cancelled.

Batch options

All fields below belong inside options. Omit fields you do not need.

Field	Type and accepted values
rewriteInstruction	String, at most 2000 characters
includeSoundEvents	Boolean
separateSpeakers	Boolean; default true for single-channel processing
maxSpeakerCount	Integer, 1–32
speakerMergeSensitivity	Number, 0.1–0.4; requires speaker separation and no maxSpeakerCount
alignmentLevel	none, word (default), character
inputEncoding	other (default, prepared container audio), pcm_s16le_16 (converted 16 kHz mono PCM)
samplingTemperature	Number, 0–2
randomSeed	Non-negative integer
separateChannels	Boolean; preserve and transcribe channels separately
channelResultMode	separate or combined
entityCategories	Array, at most 32 strings; tested examples include pii, phi, pci, all, name
redactCategories	Array, at most 32 strings; subset of entityCategories
redactionStyle	redact, replace, mask; requires redactCategories
removeDisfluencies	Boolean
identifyConversationRoles	Boolean; requires speaker separation
vocabularyHints	Array, at most 1000 strings, each at most 128 characters
processingContentStorage	Boolean; see storage limitations
exportFormats	Array of supported download formats to pre-generate at completion; every format stays downloadable
exportOptions	Array of per-format objects, described below
notifyOnCompletion	Boolean; a notification is sent when notifyUrl is present unless this is false; true requires notifyUrl
notifyUrl	Public HTTP(S) URL
clientMetadata	Object, at most two levels and 16 KB
notificationSigningSecret	Write-only signing secret; see notifications

Option combinations

• rewriteInstruction cannot be combined with entity detection, redaction or separateChannels.
• Multi-channel processing does not separate speakers. Do not combine separateChannels with maxSpeakerCount, speakerMergeSensitivity, identifyConversationRoles or pcm_s16le_16 input. The selected audio track can have at most five channels for transcription.
• Multi-channel combined results require alignment and cannot be combined with entity detection or redaction.
• matchKnownSpeakers is unavailable. Do not request it.

Each exportOptions entry has a required format and optional controls:

Field	Type / limit
includeSpeakers, includeTimestamps	Boolean, default true (the txt segment header shows both)
segmentOnSilenceLongerThanS, maxSegmentDurationS	Number greater than 0 and at most 3600 seconds
maxSegmentChars	Integer, 1–100000; counts the separators inserted when a segment is rebuilt
maxCharactersPerLine	Integer, 1–16384; wraps at word boundaries (srt, txt)

Only relevant formats use each control; json is the public transcription view. An entry applies to the pre-generated file and to later downloads of that format. Without timestamps (for example alignmentLevel: none) SRT has no timed cues and is empty. These options do not change recognition or billing.

An entity category the model rejects is detected when the task runs: the task ends FAILED with INPUT_INVALID. See parameter errors found by the model.

Response

Successful REST calls return { code: 1, message, data }. The fields below are inside data; JSON downloads are the documented exception and return the transcript view directly.

code · number

1 for success.

message · string

Result message.

data · object

Hide properties

transcriptionId · string

The MyVocal task id, also the History id.

requestId · string

The correlation id for this request.

status · string

QUEUED, PROCESSING, RECONCILING, COMPLETED, PARTIAL or FAILED.

modelId · string

myvocal_stt_v1.

billing · object

state, planKey, rateVersion, ratePerMinute, reservedCharacters, settledCharacters, releasedCharacters, billableCharacters and billableDurationMs. Characters and durations are JSON strings; convert before comparing.