Speech to Text — Batch quickstart

​

1. Read capabilities

curl https://api.myvocal.ai/sound_clone/api/v1/stt/capabilities \
  -H "accessKey: $MYVOCAL_ACCESS_KEY"

​

2. Upload the audio

SIZE_BYTES=$(python -c 'import os; print(os.path.getsize("meeting.wav"))')
UPLOAD=$(curl -s https://api.myvocal.ai/sound_clone/api/v1/stt/uploads \
  -H "accessKey: $MYVOCAL_ACCESS_KEY" -H "Content-Type: application/json" \
  -d '{"fileName":"meeting.wav","sizeBytes":'"$SIZE_BYTES"'}')
UPLOAD_ID=$(echo "$UPLOAD" | python -c "import json,sys;print(json.load(sys.stdin)['data']['uploadId'])")

# partNumber starts at 1 and runs to totalParts
curl -s https://api.myvocal.ai/sound_clone/api/v1/stt/uploads/$UPLOAD_ID/parts/1 \
  -H "accessKey: $MYVOCAL_ACCESS_KEY" -X POST
# PUT the returned part bytes, then complete:
curl -s https://api.myvocal.ai/sound_clone/api/v1/stt/uploads/$UPLOAD_ID/complete \
  -H "accessKey: $MYVOCAL_ACCESS_KEY" -H "Content-Type: application/json" \
  -d '{"parts":[{"partNumber":1,"etag":"<etag>"}]}'

​

3. Submit the transcription

# Generate once per logical task; reuse this value and the same body for retries.
IDEMPOTENCY_KEY=$(python -c 'import uuid; print(uuid.uuid4())')
curl https://api.myvocal.ai/sound_clone/api/v1/stt/transcriptions \
  -H "accessKey: $MYVOCAL_ACCESS_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"uploadId":"'"$UPLOAD_ID"'","languageHint":"en","options":{"separateSpeakers":true}}'

​

4. Poll, then download

​

Reading the result

• Language. languageHint echoes what you asked for (auto when omitted); it is not a detection result. detectedLanguage and transcript.languageCode are filled only when the model returned a language, and use the model’s three-letter code (for example eng); they are null otherwise. Real-time lines use two-letter codes (for example en). Compare languages with that difference in mind.
• Edited transcript. With rewriteInstruction, transcript.revisionStatus is APPLIED (the edited text is in transcript.revisedText), EMPTY (the model returned no edited text), FAILED (with a MyVocal revisionErrorCode) or NOT_REQUESTED. The original text, the segments and the entity offsets always refer to the original transcript.
• Plain text. txt puts a header line above each segment with its time range (when the segment is timed) and its speaker label, then the text, with a blank line between segments. Turn either part off with exportOptions (includeTimestamps: false, includeSpeakers: false).
• Subtitles. SRT needs timing: segments without timestamps (for example with alignmentLevel: none) produce no cues, so an untimed result gives an empty SRT. Line wrapping with maxCharactersPerLine breaks at word boundaries; text without spaces, or a single word longer than the limit, is split between whole characters, so no text is lost and no character is cut. maxSegmentChars counts the separators MyVocal inserts when it rebuilds a segment.

​

Options and export controls

{
  "uploadId": "<uploadId>",
  "languageHint": "en",
  "title": "Weekly sync",
  "waitForCompletion": false,
  "options": {
    "separateSpeakers": true,
    "maxSpeakerCount": 4,
    "alignmentLevel": "word",
    "entityCategories": ["pii"],
    "removeDisfluencies": true,
    "vocabularyHints": ["MyVocal", "Kubernetes"],
    "separateChannels": false,
    "exportFormats": ["txt", "json", "srt"],
    "exportOptions": [
      { "format": "srt", "maxCharactersPerLine": 42, "maxSegmentDurationS": 6 },
      { "format": "json", "includeTimestamps": true, "includeSpeakers": true }
    ]
  }
}

​

Public media URLs

​

Completion notifications

{
  "options": {
    "notifyOnCompletion": true,
    "notifyUrl": "https://customer.example/stt-callback",
    "clientMetadata": { "job": "weekly-sync" },
    "notificationSigningSecret": "<write-only secret>"
  }
}

• A notification is sent when notifyUrl is present, unless notifyOnCompletion is false. notifyOnCompletion: true without notifyUrl is refused with INPUT_INVALID; it is never silently accepted. notifyOnCompletion: false with a notifyUrl sends nothing.
• notifyUrl must be a public http/https URL; private, loopback, link-local and cloud-metadata addresses are refused on the real connection.
• notificationSigningSecret is write-only: it is stored encrypted and never returned or logged. Changing the URL or the secret under the same Idempotency-Key is a different request.
• MyVocal attempts delivery with bounded exponential backoff and a stable eventId. Delivery can fail after retries are exhausted; a receiver can also receive duplicates. Each signed delivery carries three MyVocal headers:

  Header	Meaning
  X-MyVocal-Timestamp	The signing timestamp.
  X-MyVocal-Signature	v1=<hex HMAC-SHA256(secret, timestamp + "." + rawBody)>.
  X-MyVocal-Event-Id	The stable event id, for de-duplication.

  Read the timestamp from X-MyVocal-Timestamp, then compute the HMAC over the concatenation of the timestamp, a . and the raw request body bytes:
  import hashlib, hmac
  def verify(secret: bytes, timestamp: str, raw_body: bytes, header: str) -> bool:
      expected = hmac.new(secret, timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
      return hmac.compare_digest("v1=" + expected, header)
  
  Verify against the raw bytes exactly as received; do not re-serialize the JSON, and do not sign the body without the timestamp prefix. Then de-duplicate by X-MyVocal-Event-Id.
• Polling is the authoritative result. A missed or failed callback never changes the task; do not retry the transcription because a callback was missed.

​

Complete example