La llamada básica a Whisper API no es complicada: una solicitud POST, un archivo de audio y una clave bastan para obtener el texto transcrito. Lo que realmente consume tiempo son los detalles: archivos que superan los 25 MB, formatos que no se aceptan, marcas de tiempo que no llegan o audios largos divididos cuyas líneas de tiempo quedan desalineadas.

Este artículo explica, en el mismo orden en que se integra el servicio, el endpoint y la autenticación, los formatos y límites de tamaño, la diferencia entre transcripción y traducción, los parámetros de marcas de tiempo, las llamadas con curl y con Python, la división de audios largos, los errores habituales y, al final, una lista de migración.

Nota: OpenAI y Whisper son marcas de sus respectivos titulares; este artículo solo ofrece una explicación técnica de la integración y no implica relación alguna con OpenAI. La capacidad de las interfaces, los límites de archivo y los criterios de facturación pueden cambiar; guíate por la documentación oficial y la del sitio. Los precios se consultan en la página de precios de modelos. Que una pasarela admita por completo la interfaz de audio debe confirmarse en la documentación del sitio.

1. Confirma primero el endpoint y la autenticación

La interfaz de audio no está en la misma ruta que la de conversación. La transcripción usa /v1/audio/transcriptions y la traducción usa /v1/audio/translations; ambas son POST y el cuerpo de la solicitud es multipart/form-data, no JSON. La autenticación sigue el estilo Bearer Token de OpenAI.

Elemento Descripción
Endpoint de transcripción POST /v1/audio/transcriptions
Endpoint de traducción POST /v1/audio/translations
Cabecera de autenticación Authorization: Bearer <API_KEY>
Tipo de solicitud multipart/form-data
Base URL oficial https://api.openai.com/v1
Base URL de la pasarela https://ai.zhongshangqihang.com/v1; el alcance de la interfaz de audio depende de la documentación del sitio

La clave debe residir únicamente en el servidor. Si aparece en el navegador, en una aplicación o en un repositorio público, equivale a entregar la cuenta. Cada pasarela reenvía un conjunto distinto de interfaces de audio, así que antes de integrar conviene confirmar en la página de precios de modelos o en la documentación del sitio si el modelo está disponible.

2. Formatos admitidos y límite de 25 MB

Los formatos de entrada que documenta el servicio son mp3, mp4, mpeg, mpga, m4a, wav y webm, con un máximo de 25 MB por archivo. Formatos como flac u ogg no deben darse por supuestos: conviene convertirlos antes de subirlos.

Los 25 MB son un límite de tamaño de archivo, no de duración. Cuanto mayor es el bitrate, menos duración cabe en el mismo tamaño: un mp3 mono a 16 kHz puede contener mucho audio, mientras que un wav estéreo a 48 kHz puede superar el límite en pocos minutos. Convertir todo a 16 kHz, mono, mp3 o wav antes de subir es el preprocesamiento más estable.

3. Transcribir y traducir no son lo mismo

/audio/transcriptions convierte el audio en texto en el idioma original: un audio en chino produce texto en chino. /audio/translations traduce el audio al inglés; la documentación oficial indica que solo admite traducción al inglés y que usa whisper-1. Para subtítulos en el idioma original hay que usar la transcripción, no la interfaz de traducción.

El parámetro de idioma usa códigos ISO-639-1, por ejemplo zh, en o ja. Si no se envía, el modelo lo detecta automáticamente, pero con audios cortos, mezcla de idiomas o acentos marcados es fácil que se equivoque. Cuando el idioma del negocio está claro, especificarlo resulta más fiable.

4. Ejemplo mínimo con curl

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"

Hay tres puntos que suelen fallar: el campo del archivo debe ir con -F; timestamp_granularities[] debe incluir los corchetes; y solo verbose_json devuelve la estructura por segmentos. Si la pasarela no admite algún parámetro, quítalo primero y vuelve a probar para localizar el problema paso a paso.

5. Llamada con Python y marcas de tiempo

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}")

Las marcas de tiempo tienen dos niveles: segment es el nivel de frase o segmento, útil para subtítulos y actas de reunión; word es el nivel de palabra, adecuado para alineación palabra por palabra. La documentación oficial indica que timestamp_granularities[] solo surte efecto con whisper-1 y requiere verbose_json. Los modelos de transcripción más recientes pueden ofrecer mejor precisión, pero su soporte de marcas de tiempo y formatos de subtítulo es distinto; conviene revisar la documentación antes de elegir.

En escenarios con muchos nombres propios se puede usar prompt para pasar nombres de personas, productos y terminología. La documentación oficial señala que el límite del prompt de whisper-1 es de 224 tokens y que lo que exceda puede truncarse, así que conviene incluir solo las palabras más importantes.

Si solo se necesita el texto, response_format puede ser json o text; para archivos de subtítulos se puede pedir directamente srt o vtt. Cuantos más formatos se solicitan, mayor es el cuerpo de la respuesta; en procesos por lotes hay que sopesar el ancho de banda y el costo de análisis.

6. Los audios largos se dividen antes de transcribir

Los audios que superan los 25 MB deben dividirse. El flujo recomendado es el siguiente:

  1. Convertir todo con ffmpeg a 16 kHz mono para reducir el tamaño.
  2. Cortar por detección de silencios o en tramos fijos de 10 minutos, evitando cortar a mitad de frase.
  3. Registrar el desplazamiento inicial de cada tramo; por ejemplo, part_000 corresponde al segundo 0 y part_001 al segundo 600.
  4. Llamar a la interfaz de transcripción tramo por tramo y guardar la respuesta original.
  5. Al unir el texto, sumar el desplazamiento a las marcas de tiempo de cada tramo.
  6. Revisar por muestreo cerca de los puntos de corte para corregir palabras repetidas o perdidas.

Entre un tramo y otro se puede dejar un solapamiento de 0,5 a 1 segundo para reducir palabras perdidas en los bordes, pero la parte solapada se transcribe dos veces y hay que eliminarla al unir. El script de división debe guardar también la lista de desplazamientos; no conviene adivinar los tiempos por el nombre del archivo. Que los nombres, el orden y los desplazamientos no coincidan es el accidente más frecuente en la fase de unión. La concurrencia reduce el tiempo total, pero no debe superar el límite de velocidad de la cuenta; de lo contrario, los reintentos por error 429 terminan frenando el proceso completo.

7. Cómo diagnosticar los errores habituales

  • 401: clave incorrecta o vencida, o falta Bearer.
  • 404: Base URL o ruta mal escrita; confirma /v1/audio/transcriptions.
  • 400: formato no admitido, parámetro mal escrito o modelo que no admite ese parámetro.
  • 413: el archivo supera el límite de tamaño; comprime o divide.
  • 429: se superó la concurrencia o la cuota; reduce la concurrencia y reintenta con espera exponencial.
  • 5xx o tiempo de espera agotado: problema del servidor o de la red; limita el número de reintentos para evitar cobros duplicados.
  • Texto vacío: audio en silencio, volumen demasiado bajo o idioma mal detectado; revisa el audio y especifica language.
  • Sin marcas de tiempo: response_format no es verbose_json o el modelo no es whisper-1.

8. Lista de migración de la API oficial a una pasarela

  1. Confirma la Base URL y la ruta de la interfaz de audio de la pasarela de destino.
  2. Verifica que el modelo que vas a usar esté disponible en el sitio y que el nombre coincida con el oficial.
  3. Cambia el cuerpo JSON por multipart/form-data.
  4. Ajusta response_format y revisa si el código depende del campo segments.
  5. Comprueba si se admiten los parámetros de marcas de tiempo; si no, vuelve al nivel de segmento o haz la alineación localmente.
  6. Define tiempos de espera y un número máximo de reintentos razonables.
  7. No registres en los logs la URL completa del audio ni la clave; trata los resultados de texto como datos sensibles.
  8. Haz una regresión con audios reales del negocio y compara la tasa de error de caracteres y la línea de tiempo.
  9. Prepara una ruta de degradación: cambiar de modelo, de región o volver a la interfaz oficial.

Preguntas frecuentes

¿Cuál es la diferencia entre Whisper API y el modelo Whisper de código abierto?

El modelo de código abierto se puede desplegar por cuenta propia, los datos permanecen en local, pero hay que asumir el costo de GPU, operación y ajuste. La API alojada evita el despliegue y cobra por uso, lo que encaja en lanzamientos rápidos y tráfico variable.

¿Los 25 MB son un límite de duración?

No, son un límite de tamaño de archivo. Bajar el bitrate y convertir a mono alarga bastante la duración que se puede subir; si se supera el límite, hay que dividir.

¿Por qué no obtengo marcas de tiempo por palabra?

Las marcas por palabra requieren que se cumplan a la vez whisper-1, verbose_json y timestamp_granularities=["word"]. Cambiar de modelo o de formato puede hacer que el campo desaparezca.

¿La interfaz de traducción puede traducir inglés a chino?

No. La interfaz oficial de traducción solo produce inglés. Para el chino hay que usar la transcripción y después traducir el texto con un modelo de texto.

¿Puedo reemplazar directamente la Base URL oficial por la de una pasarela?

En las interfaces de texto suele funcionar; en las de audio depende de si la pasarela reenvía la ruta y los parámetros correspondientes. Antes de integrar, haz una validación completa con un audio corto y no des la compatibilidad por hecha.

Siguiente paso

Primero regístrate en ZSQH AI Gateway, crea una clave de prueba y transcribe un audio de un minuto; después valida las marcas de tiempo y la división de audios largos. Los modelos y los precios figuran en precios de modelos.

Lecturas relacionadas: