Developer Guides8 min read

Speech-to-Text API with cURL: Transcribe Audio from the Command Line

Transcribe audio with cURL and Privocio's speech-to-text API. Batch uploads, OpenAI-compatible routes, and SSE streaming from your terminal or CI pipeline.

Sarah MitchellVoice Infrastructure Engineer
Developer terminal on laptop running curl to upload audio for speech-to-text transcription
Quick answer: You can transcribe audio with Privocio using curl and a Bearer token. POST a multipart file to https://api.privocio.com/v1/transcriptions with model=whisper-1 and read JSON from stdout — no SDK required.

Shell access is often the fastest way to verify an API key, debug uploads, or script transcription in CI. This guide shows cURL speech-to-text recipes for Privocio's private STT API.

For language-specific tutorials, see Python, JavaScript, and Go guides.

Prerequisites

    • curl 7.x+ (for -F multipart uploads)
    • a Privocio API key (authentication)
    • an audio file, e.g. recording.wav

Export your key:

export PRIVOCIO_API_KEY="YOUR_API_KEY"

Health check (no auth)

curl -sS https://api.privocio.com/healthz | jq .

Batch transcription

curl -sS -X POST "https://api.privocio.com/v1/transcriptions" \
  -H "Authorization: Bearer $PRIVOCIO_API_KEY" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "model=whisper-1" \
  -F "language=en" | jq .

The response JSON includes the transcript text. Large files may take several minutes — add --max-time 600 if needed.

OpenAI-compatible route

curl -sS -X POST "https://api.privocio.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $PRIVOCIO_API_KEY" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "model=whisper-1" \
  -F "language=en" | jq .

Same Whisper-style contract as OpenAI — useful when migrating scripts. See migrate from OpenAI Whisper.

Streaming transcription (SSE)

curl -N -sS -X POST "https://api.privocio.com/v1/transcriptions/stream" \
  -H "Authorization: Bearer $PRIVOCIO_API_KEY" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "model=whisper-1"

The -N flag disables buffering so SSE segments print as they arrive. Details: streaming docs.

Agent output mode (token savings)

curl -sS -X POST "https://api.privocio.com/v1/transcriptions" \
  -H "Authorization: Bearer $PRIVOCIO_API_KEY" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "model=whisper-1" \
  -F "language=en" \
  -F "output_mode=agent" | jq .

Learn about output modes for LLM pipelines.

Common errors

HTTPCauseFix
401Bad or missing keyCheck `Authorization: Bearer`
413File too largeCompress or split audio
415Wrong MIME typeSet `type=audio/wav` on the file part
502Runtime busyRetry with backoff

Best practices

    • Store PRIVOCIO_API_KEY in CI secrets, not shell history
    • Use jq to extract .text in scripts
    • Pin API base URL in config for staging vs production
    • Review security and pricing before production volume

Frequently Asked Questions

Can I use cURL in CI/CD?

Yes. Upload artifacts from build pipelines the same way — ideal for smoke tests after deploy.

Do I need an SDK?

No. cURL is enough for batch and streaming. SDKs add ergonomics in app code.

Is this Whisper-compatible?

Yes — whisper-1 and /v1/audio/transcriptions match OpenAI's shape. Compare Privocio vs OpenAI Whisper.

Where are full cURL examples?

The API docs cURL section lists every endpoint.

Conclusion

cURL is the zero-dependency way to call Privocio's speech-to-text API — perfect for debugging, scripts, and ops workflows.

speech-to-textwhisper