Whisper is OpenAI's open-source speech recognition model, and OpenAI also provides a hosted audio transcription endpoint. For developers, the easiest approach is usually not to deploy the model yourself, but to get a key, call /v1/audio/transcriptions, upload an audio file, and receive text.

This article covers how to get a key, how to call the endpoint, what file limits apply, how to get timestamps, and the common errors and privacy issues to watch for. Different gateways support different parts of the audio API, so refer to the on-site documentation.

Note: OpenAI and Whisper are trademarks of their respective owners. This article is for technical integration only. Model names, file limits, and billing rules may change. Refer to the official and on-site documentation, and to the on-site pricing page for prices.

1. What the Whisper API can do

  • Transcribe meetings, interviews, and lecture recordings;
  • Produce first-draft subtitles for podcasts and short videos;
  • Run quality checks and keyword extraction on customer service calls;
  • Clean up voice notes;
  • Transcribe and translate multilingual audio (translation uses a separate endpoint).

It is not suitable for high-accuracy recognition in very noisy environments, meetings that require speaker diarization, or forensic-grade audio analysis. For those cases, add human proofreading after transcription or use a dedicated speaker-diarization solution.

2. Getting a Whisper API key

There is no separate "Whisper key." Whisper reuses an API key from the OpenAI platform or from a gateway. When this article says Whisper API key, it means a key that can call the audio transcription endpoint.

Option one: OpenAI directly

  1. Register an OpenAI platform account and configure a payment method.
  2. Create a key on the API Keys page and name it by project.
  3. Confirm that the account has available credit.
  4. Store the key in a server-side environment variable.

Option two: the ZSQH AI Gateway

  1. Open the ZSQH AI Gateway, register, and sign in.
  2. Go to the API keys page and create a new key.
  3. Check the model pricing page or the on-site documentation to confirm that an audio transcription model is available.
  4. Top up a small amount and test with a short audio clip first.

Whichever path you choose, keep the key on the server only. A key held directly in a browser or mobile app front end is effectively handing the account to someone else.

3. Base URL and authentication

Item Official OpenAI ZSQH AI Gateway
Base URL https://api.openai.com/v1 https://ai.zhongshangqihang.com/v1
Authentication Authorization: Bearer <key> Same
Endpoint /audio/transcriptions Per on-site documentation
Model whisper-1 and others Per on-site documentation or pricing page

Whether a gateway fully forwards the audio endpoint, and which response_format values it supports, depends on the on-site documentation. Do not assume that because text endpoints work, audio endpoints work too.

4. Calling with curl

export WHISPER_API_KEY="sk-your-key"

curl "https://ai.zhongshangqihang.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1" \
  -F "language=en" \
  -F "response_format=json"

Note that this is multipart/form-data, not JSON. Use -F rather than -d, or the server will not receive the file.

5. Calling from Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["WHISPER_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",  # check the on-site documentation
        file=f,
        language="en",
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )

for seg in result.segments:
    print(f"{seg.start:.1f}-{seg.end:.1f}  {seg.text}")

language takes an ISO-639-1 code such as en, zh, or ja. If you omit it, the model detects the language automatically, but short clips or mixed-language audio are easy to misclassify. Specifying it explicitly is more reliable.

6. File formats and size limits

Item Common limit Recommendation
Supported formats flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm Convert everything to mp3 or wav
Single file size 25 MB (check official documentation) Split files that exceed it
Sample rate No hard requirement 16 kHz mono is sufficient
Duration Indirectly limited by file size Split long audio into 10-minute segments
Multi-channel Supported, but recognition quality is average Mix down or select the primary channel first

An unsupported format returns 400; an oversized file usually returns 413. Transcoding is the most reliable preprocessing step.

7. Timestamps and output formats

response_format What it returns Best for
json Plain text When you only need the words
text Plain text with a simpler response body Script pipelines
srt Subtitle file Video editing
vtt Web subtitles Web players
verbose_json Text, segments, language, and duration When you need timestamps

Use timestamp_granularities=["segment"] for segment-level timestamps. Word-level timestamps are usually available only for whisper-1 and require verbose_json. Check the official or on-site documentation for exact support.

8. Handling long audio

For audio that exceeds the size limit, split it with ffmpeg and transcribe each part:

ffmpeg -i input.mp3 -f segment -segment_time 600 \
  -ac 1 -ar 16000 -b:a 64k part_%03d.mp3

When splitting:

  1. Cut at silence where possible so words are not split in half.
  2. Record the start offset of each segment and add it back when merging timestamps.
  3. Overlap adjacent segments by 0.5–1 second to reduce dropped words at the boundaries.
  4. Deduplicate and fix punctuation once after merging.

9. Common errors

Error Cause What to do
401 Wrong key or missing Bearer Check the key and request headers
404 Wrong base URL or path Confirm /v1/audio/transcriptions
400 unsupported file Unsupported format Convert to mp3 or wav
413 File too large Compress or split it
429 Rate or quota limit exceeded Reduce concurrency and retry with backoff
Empty transcript Silence, low volume, or wrong language detection Check the audio and set language explicitly
Timeout Large file or slow network Split the file and increase the timeout

10. Cost control

  1. Run silence detection before transcription and remove blank sections.
  2. Convert everything to 16 kHz mono to reduce file size.
  3. Split long audio and process segments in parallel, but cap concurrency to avoid 429 responses.
  4. Test language and quality on short samples before submitting a batch.
  5. Record the audio duration of every call and reconcile costs by project.
  6. Cap failed retries to avoid duplicate billing.

Audio transcription is usually billed per minute. See the on-site model pricing for rates. A low unit price does not always mean lower total cost: format conversion, human proofreading, and retries all add to the bill.

11. Improving accuracy

  1. Preprocess the audio: convert to 16 kHz mono, apply light noise reduction, and remove clipping and long silences.
  2. Set the language explicitly: pass language=zh for Chinese content, and evaluate segmenting mixed Chinese-English audio.
  3. Provide a prompt: pass proper nouns, names, and product names through the prompt parameter to guide the model's vocabulary.
  4. Split sensibly: cut at silence and keep segments to 5–10 minutes to avoid dropped words at boundaries.
  5. Proofread afterward: validate numbers, dates, amounts, and proper nouns with rules, and use human review for critical content.
  6. Maintain a glossary: turn frequent misrecognitions into a replacement table and update it as versions change.

There is no universal accuracy number. Results depend heavily on recording quality, accents, and domain vocabulary. Before launch, run a sample test on real audio from your own business; that is more meaningful than published benchmarks.

12. Privacy and compliance

  • Audio may contain personal information such as names, phone numbers, addresses, and medical details. Inform users and obtain authorization before uploading.
  • Redact sensitive content first, or use a solution that can be deployed privately.
  • Confirm the provider's retention policy, logging policy, and deletion method.
  • Do not place audio containing customer data at publicly accessible URLs.
  • Assess local regulations and corporate compliance requirements for cross-border transfers.

FAQ

Does the Whisper API support Chinese?

Yes. For Chinese transcription, pass language=zh explicitly and add proper nouns through the prompt or post-processing.

Can one key call text models as well?

On a gateway, usually yes, but whether the audio endpoint is enabled depends on the on-site documentation. Permissions for an official key are configured by account and project.

Can it return word-level timestamps?

Some models and formats support it, usually requiring verbose_json plus timestamp_granularities. Check the documentation.

What if the audio is larger than 25 MB?

Compress it with ffmpeg or split it into 10-minute segments, transcribe each one, and merge the results. Cut at silence where possible.

Can transcription output be used commercially?

It depends on the rights to the audio content, the platform terms, and local law. When other people's recordings, music, or course content are involved, confirm authorization first.

Next steps

Register for the ZSQH AI Gateway, create a test key, run a one-minute audio clip through /v1/audio/transcriptions, and then connect it to your batch pipeline. Models and prices are subject to model pricing.

Related reading: