API examples: recordings to transcripts and RAG passages

For a guided first try, watch the 36-second walkthrough and follow the recording-to-RAG tutorial, or copy the public preset task.

Run andronixmd/speech-to-text-transcriber with the public 45-second speech sample. The examples use a $0.10 maximum run charge, 4,096 MB memory and a 180-second Actor timeout. Check the Actor’s current Pricing tab before running; the cap can stop processing before a result is complete. This is a budget example, not a promise of a particular final price.

Export passages for your RAG pipeline

For source-timed passages, add "exportRag": true to the input object in a copy of one of the scripts below, keeping "timestamps": "segment". Their existing default remains transcript/subtitle export; they do not download JSONL automatically.

After the run, read rag_chunks from every complete Dataset item, or fetch transcript-NNN.rag.jsonl from the run’s KVS. NNN is the zero-based input position. When a Dataset row contains result_record_key, read its full record’s value wrapper first. Keep the scripts’ billing/error checks before indexing any text.

Store each passage’s text with source_url, start_s, end_s and optional language/speaker. Passage id is local to one recording, so namespace it in your own corpus. Embeddings, indexing and answer generation run in your system. The RAG tutorial walks through that boundary. The RAG Task already selects the required options.

Prepaid access for agents

An agent can buy a temporary Apify API token through Apify AGI using a supported funded wallet/payment client, without ordinary Apify registration. The minimum purchase is $1; the token expires after 14 days and unused credit is non-refundable. Check current payment terms before purchasing. Keep the returned token secret and use it as APIFY_TOKEN in the same API examples below. Never give a buyer your Actor publisher token.

On October 24, 2026, an x402 exact payment of 1 USDC on Base returned a prepaid token. Two live build 0.2.4 runs, one through REST and one through central MCP, each transcribed the 45.3-second sample with a $0.10 run cap. Both returned eight segments and downloadable SRT/VTT, and later run counters showed $0.0352 in events per run. This verifies that path for this sample. Other payment protocols have not been tested with these examples.

For an MCP client supporting remote servers and Bearer headers, use:

{
  "mcpServers": {
    "polyglot-stt": {
      "url": "https://mcp.apify.com/?tools=call-actor,fetch-actor-details",
      "headers": { "Authorization": "Bearer <prepaid Apify token>" }
    }
  }
}

Read the Actor’s input schema with fetch-actor-details, then call call-actor once with these arguments:

{
  "actor": "andronixmd/speech-to-text-transcriber",
  "input": {
    "urls": ["https://storage.googleapis.com/cloud-samples-data/speech/commercial_mono.wav"],
    "timestamps": "segment"
  },
  "waitSecs": 0,
  "callOptions": {
    "maxTotalChargeUsd": 0.10,
    "memory": 4096,
    "timeout": 180
  }
}

The current dedicated Actor tool does not expose callOptions; use the generic tool when a per-run monetary cap is required. Save its runId, poll with get-actor-run, read the Dataset with get-dataset-items, and fetch subtitles with get-key-value-store-record. Those reading tools are loaded automatically with call-actor. The prepaid balance caps the account across Actors; a run cap does not cap new runs or retries. Check the balance at GET https://agi.apify.com/prepaid-tokens/balance with the same Bearer header. Observed balance and run-event updates lagged completion; reconcile them after processing instead of treating the first unchanged balance as free usage.

JavaScript or Python: complete runnable examples

Download JavaScript or Python. Both use the language’s standard library, so no Apify SDK installation is needed. Use Node.js 22+ or Python 3. Set your Apify token in your shell without putting it in a URL or Actor input:

export APIFY_TOKEN='your-apify-token'
node transcribe.mjs
# Or:
python3 transcribe.py

Run in a directory where you want to save subtitles. On success, each script prints the run ID and transcript, then saves and prints the paths transcript-000.srt and transcript-000.vtt. These names come from the position of the URL in urls, never from untrusted media filenames. Existing files with those names are replaced. To transcribe your own recording, replace the sample URL in the script’s input object with a publicly fetchable HTTPS media URL.

Each script sends the creation POST once, waits with at most 12 status GETs (each waiting up to 20 seconds), and follows Dataset pagination through every row. A SUCCEEDED run can still contain item errors or incomplete billing: both scripts check error, stop_processing, billing.stop, billing.status of partial or unknown, missing transcript content, and subtitle publication errors. Complete items are printed/downloaded; incomplete items produce a failure instead of being treated as finished. An empty Dataset or a result count different from the number of submitted URLs also fails.

An oversized Dataset row can contain result_record_key, such as item-000-result, instead of inline text. The scripts fetch that record from the run’s defaultKeyValueStoreId, unwrap the signed wrapper’s value, and keep the same error and billing checks. They do not verify its HMAC signature. Subtitle downloads use the source-language records transcript-NNN.srt and transcript-NNN.vtt in that same store.

If a start response is lost, reconcile existing runs through the authenticated run-list API, or the Actor’s Runs page in Apify Console, before trying again: a network error does not prove the POST failed. If a printed run ID is still running when the local wait ends, inspect or continue polling that run. Do not automatically create another one. Local timeouts do not abort the run.

For long recordings, start asynchronously, save the run ID durably, and use an Apify completion webhook or your job system to fetch output after completion. Set an appropriate run timeout and budget for that workload; these short-demo limits are not intended for hours of audio. Do not hold a synchronous request open for a four-hour recording.

HTTP: the same requests with curl

These requests show the REST contract directly. Use the scripts above when you want automatic status checks, pagination, per-item failure handling and downloads. Keep tokens in the Authorization header. Never add --retry to the creation POST.

Start exactly one run and save the response:

curl --fail-with-body --max-time 30 \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"urls":["https://storage.googleapis.com/cloud-samples-data/speech/commercial_mono.wav"],"timestamps":"segment"}' \
  'https://api.apify.com/v2/actors/andronixmd~speech-to-text-transcriber/runs?maxTotalChargeUsd=0.1&memory=4096&timeout=180' \
  -o run.json

Copy data.id from run.json into RUN_ID. Request its status at most 12 times, stopping when data.status is SUCCEEDED, FAILED, TIMED-OUT or ABORTED:

RUN_ID='copy-data.id'
curl --fail-with-body --max-time 30 \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  "https://api.apify.com/v2/actor-runs/$RUN_ID?waitForFinish=20" \
  -o status.json

Only consume completed output after SUCCEEDED; inspect saved output for other terminal statuses. If still running after the bounded wait, retain this run ID and continue later. Copy data.defaultDatasetId and data.defaultKeyValueStoreId from the final status response:

DATASET_ID='copy-data.defaultDatasetId'
STORE_ID='copy-data.defaultKeyValueStoreId'
OFFSET=0
curl --fail-with-body --max-time 30 \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -D dataset-headers.txt \
  "https://api.apify.com/v2/datasets/$DATASET_ID/items?format=json&offset=$OFFSET&limit=100" \
  -o items.json

Read all pages: increment OFFSET by the number of rows actually received, repeat the GET, and stop only when it reaches X-Apify-Pagination-Total from the response headers. Do not use clean, skipEmpty, field selection or other filters that could hide errors or change row positions. Compare the total row count with the number of input URLs. Zero rows can mean processing stopped at startup.

Inspect every item’s error and billing fields listed above. If a row instead points to result_record_key, retrieve the exact key (here the first URL’s key):

curl --fail-with-body --max-time 30 \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  "https://api.apify.com/v2/key-value-stores/$STORE_ID/records/item-000-result" \
  -o full-result.json

Read value.text and inspect value.error, value.stop_processing and value.billing as well as the Dataset row’s metadata. Download source subtitles only after these checks succeed:

for EXTENSION in srt vtt; do
  curl --fail-with-body --max-time 30 \
    -H "Authorization: Bearer $APIFY_TOKEN" \
    "https://api.apify.com/v2/key-value-stores/$STORE_ID/records/transcript-000.$EXTENSION" \
    -o "transcript-000.$EXTENSION" || break
done

For later input URLs replace 000 with their zero-padded input index. Do not re-run the Actor merely because a download failed; fetch the saved record again.

Inspect an existing sample without a paid run

See the sample result JSON and sample Dataset. The Actor’s API tab also provides generated SDK/HTTP examples, CLI instructions and its OpenAPI description. The examples here supplement those with output recovery, budget checks and subtitle downloads.

Verification and references

Offline tests exercise both runnable scripts with fake HTTP responses: exactly one start, all Dataset pages, inline/full-record results, errors and billing stops, subtitle contents and filenames, empty results and lost creation responses. On October 23, 2026, the JavaScript example passed one live run on Actor build 0.2.4, including transcript output and matching SRT/VTT downloads. The Python example and webhook delivery have not been tested live.

REST references: start a run, get run status, Dataset pagination, download a record.