The basic Whisper API call is not complicated: one POST request, one audio file, and one key are enough to get transcribed text back. What actually takes time is the details: a file over 25 MB, an unsupported format, missing timestamps, or a timeline that drifts after long audio has been split.

This article follows the integration order: endpoints and authentication, format and size limits, the difference between transcription and translation, timestamp parameters, both curl and Python calls, splitting long audio, common errors, and finally a migration checklist.

Note: OpenAI and Whisper are trademarks of their respective owners. This article is for technical integration only and has no affiliation with OpenAI. API capabilities, file limits, and billing rules may change; refer to the official documentation and the on-site documentation. For prices, refer to on-site model pricing. Whether a given gateway fully supports the audio API is subject to the on-site documentation.

1. Confirm the endpoint and authentication first

The audio API and the chat API do not live at the same path. Transcription uses /v1/audio/transcriptions, translation uses /v1/audio/translations; both are POST, and the request body is multipart/form-data, not JSON. Authentication follows the OpenAI-style Bearer token.

Item Description
Transcription endpoint POST /v1/audio/transcriptions
Translation endpoint POST /v1/audio/translations
Authentication header Authorization: Bearer <API_KEY>
Request type multipart/form-data
Official base URL https://api.openai.com/v1
Gateway base URL https://ai.zhongshangqihang.com/v1; audio API coverage is subject to the on-site documentation

Keep the key on the server only. A key that appears in a browser, a mobile app, or a public repository is equivalent to handing over the account. Different gateways forward different parts of the audio API, so before integrating, check model pricing or the on-site documentation to confirm the model is available.

2. Supported formats and the 25 MB limit

The officially listed input formats are mp3, mp4, mpeg, mpga, m4a, wav, and webm, with a 25 MB limit per file. Do not assume flac, ogg, and similar formats will work; transcode them before uploading.

25 MB is a file-size limit, not a duration limit. The higher the bitrate, the shorter the audio that fits into the same size: a 16 kHz mono mp3 can hold a long recording, while a 48 kHz stereo wav may exceed the limit in a dozen minutes. Converting everything to 16 kHz mono mp3 or wav before upload is the most reliable preprocessing step.

3. Transcription and translation are not the same thing

/audio/transcriptions converts audio into text in the original language, so Chinese audio produces Chinese text. /audio/translations translates audio into English; the official documentation explicitly states that only English output is supported, and that it uses whisper-1. When you need Chinese subtitles, use transcription and do not expect the translation endpoint to do it.

Language parameters use ISO-639-1 codes such as zh, en, and ja. If you omit the parameter, the model detects the language automatically, but short clips, mixed Chinese and English, or heavy accents can lead to misdetection. When the business language is known, specifying it explicitly is more reliable.

4. Minimal curl example

curl "https://ai.zhongshangqihang.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1" \
  -F "language=zh" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=segment"

Three things to note: use -F for the file field; timestamp_granularities[] must include the square brackets; and only verbose_json returns the segment structure. If a gateway does not expose a given parameter, remove it and test again to isolate the problem step by step.

5. Python calls and timestamps

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",
        file=f,
        language="zh",
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )

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

Timestamps come at two levels: segment is sentence-level and suits subtitles and meeting notes; word is word-level and suits word-by-word alignment. The official documentation states that timestamp_granularities[] currently applies only to whisper-1 and requires verbose_json. Newer transcription models may be more accurate, but their support for timestamps and subtitle formats differs, so check the documentation before choosing one.

For content full of proper nouns, you can pass names, product names, and terminology through prompt. The official documentation states that the prompt limit for whisper-1 is 224 tokens, and excess may be truncated, so include only the most important terms.

When you only need text, set response_format to json or text; for subtitle files you can request srt or vtt directly. The more formats involved, the larger the response body, so in batch scenarios weigh bandwidth and parsing costs.

6. Split long audio before transcribing

Audio over 25 MB must be split. Recommended workflow:

  1. Use ffmpeg to convert everything to 16 kHz mono and reduce the size.
  2. Split by silence detection or in fixed 10-minute segments, avoiding cuts in the middle of a sentence.
  3. Record the start offset of each segment, for example part_000 at 0 seconds and part_001 at 600 seconds.
  4. Call the transcription endpoint segment by segment and save the raw responses.
  5. When merging text, add each segment's offset back to its timestamps.
  6. Sample-check around the cut points to handle repeated words and dropped words.

You can leave 0.5–1 second of overlap between segments to reduce word loss at boundaries, but the overlapping audio will be transcribed twice, so it must be deduplicated during merging. The splitting script should save the offset list together with the files; do not guess timing from file names. A mismatch between file names, order, and offsets is the most common accident during merging. Concurrency can shorten total processing time, but do not exceed the account's rate limits, or 429 retries will end up slowing everything down.

7. Troubleshooting common errors

  • 401: wrong or expired key, or the Bearer prefix is missing.
  • 404: wrong base URL or path; confirm it is /v1/audio/transcriptions.
  • 400: unsupported format, misspelled parameter, or a model that does not support the parameter.
  • 413: file exceeds the size limit; compress or split it.
  • 429: concurrency or quota exceeded; reduce concurrency and retry with exponential backoff.
  • 5xx or timeout: server or network issue; cap the number of retries to avoid duplicate billing.
  • Empty text returned: silent audio, volume too low, or language misdetection; inspect the audio and specify language.
  • No timestamps: response_format is not verbose_json, or the model is not whisper-1.

8. Migration checklist from official API to a gateway

  1. Confirm the target gateway's base URL and audio API path.
  2. Confirm the model you need is available on-site, with a name identical to the official one.
  3. Change the JSON request body to multipart/form-data.
  4. Align response_format and check whether your code depends on the segments field.
  5. Verify whether timestamp parameters are supported; if not, fall back to segment level or local alignment.
  6. Set reasonable timeouts and a maximum retry count.
  7. Do not log complete audio URLs or keys, and treat text results as sensitive data.
  8. Run a regression with a set of real business audio files, comparing word error rate and timeline accuracy.
  9. Prepare a fallback path: another model, another region, or a return to the official API.

Frequently asked questions

What is the difference between the Whisper API and the open-source Whisper model?

The open-source model can be self-hosted and keeps data local, but you bear the cost of GPUs, operations, and tuning. A hosted API removes deployment work and bills by usage, which suits fast launches and fluctuating traffic.

Is 25 MB a limit on audio duration?

No, it is a file-size limit. Lowering the bitrate and converting to mono can significantly extend the uploadable duration; if you still exceed the limit, split the file.

Why can't I get word-level timestamps?

Word-level timestamps require whisper-1, verbose_json, and timestamp_granularities=["word"] together. Changing the model or the format can cause the field to be missing.

Can the translation endpoint translate English into Chinese?

No. The official translation endpoint outputs English only. For Chinese, use the transcription endpoint and then translate the text with a text model.

Can a gateway replace the official base URL directly?

Text endpoints usually can; for audio endpoints it depends on whether the gateway forwards the corresponding path and parameters. Run a complete test with a short audio clip before integrating, and do not assume compatibility.

Next steps

Register for the ZSQH AI Gateway, create a test key, run a one-minute audio clip through transcription, and then verify timestamps and long-audio splitting. Models and prices are subject to model pricing.

Related reading: