Whisper es un modelo de reconocimiento de voz de código abierto desarrollado por OpenAI, que además ofrece una interfaz alojada de transcripción de audio. Para un desarrollador, la opción más cómoda no es desplegar el modelo por su cuenta, sino obtener una clave, llamar a /v1/audio/transcriptions, subir el archivo de audio y recibir el texto directamente.

Este artículo explica cómo obtener la clave, cómo llamar a la interfaz, qué límites tienen los archivos, cómo obtener marcas de tiempo y qué errores y problemas de privacidad son habituales. Cada pasarela admite un alcance distinto de interfaces de audio; guíate por la documentación del sitio.

Nota: OpenAI y Whisper son marcas de sus respectivos titulares; este artículo solo ofrece una explicación técnica de la integración. Los nombres de modelo, los límites de archivo y los criterios de facturación pueden cambiar; guíate por la documentación oficial y la del sitio, y consulta los precios en la página de precios del sitio.

1. Qué puede hacer la API de Whisper

  • Transcribir reuniones, entrevistas y grabaciones de cursos;
  • Crear borradores de subtítulos para pódcast y vídeos cortos;
  • Control de calidad de llamadas de atención al cliente y extracción de palabras clave;
  • Organizar notas de voz;
  • Transcribir y traducir audio en varios idiomas (la interfaz de traducción se trata aparte).

No es adecuada para: reconocimiento de alta precisión en entornos con mucho ruido, reuniones que requieren separación de hablantes o peritajes forenses de grabaciones. En esos casos hay que añadir revisión humana después de la transcripción o elegir una solución específica de separación de hablantes.

2. Obtener una clave de API de Whisper

Whisper no tiene una "clave de Whisper" independiente; reutiliza la clave de API de la plataforma OpenAI o de la pasarela. La "clave de API de Whisper" de la que hablamos aquí es esa clave capaz de llamar a la interfaz de transcripción de audio.

Opción uno: OpenAI oficial

  1. Regístrate en la plataforma OpenAI y configura un método de pago.
  2. Crea una clave en la página de API Keys y ponle un nombre por proyecto.
  3. Confirma que la cuenta tiene cuota disponible.
  4. Guarda la clave en una variable de entorno del servidor.

Opción dos: pasarela de IA de ZSQH

  1. Abre la pasarela de IA de ZSQH, regístrate e inicia sesión.
  2. Entra en la página de claves de API y crea una nueva.
  3. Comprueba en precios de modelos o en la documentación del sitio si el modelo de transcripción de audio está disponible.
  4. Recarga una cantidad pequeña y prueba primero con un audio corto.

Sea cual sea la vía, la clave debe residir solo en el servidor. Si el navegador o el frontend de la aplicación la contienen, estás entregando la cuenta a terceros.

3. Base URL y autenticación

Elemento OpenAI oficial Pasarela ZSQH
Base URL https://api.openai.com/v1 https://ai.zhongshangqihang.com/v1
Autenticación Authorization: Bearer <key> Igual
Interfaz /audio/transcriptions Según la documentación del sitio
Modelo whisper-1, etc. Según la documentación o la página de precios del sitio

Que la pasarela reenvíe por completo la interfaz de audio y qué valores de response_format admite debe confirmarse en la documentación del sitio. No des por hecho que, porque la interfaz de texto funciona, la de audio también lo hará.

4. Llamada con curl

export WHISPER_API_KEY="sk-tu-clave"

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

Ojo: esto es multipart/form-data, no JSON. Usa -F en lugar de -d; de lo contrario, el servidor no recibirá el archivo.

5. Llamada con 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("reunion.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",  # según la documentación del sitio
        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}")

language usa códigos ISO-639-1, por ejemplo zh, en, ja. Si no lo indicas, el modelo lo detecta automáticamente, pero con audios cortos o con mezcla de idiomas es fácil que se equivoque; especificarlo es más fiable.

6. Formatos de archivo y límites de tamaño

Elemento Límite habitual Recomendación
Formatos admitidos flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm Convierte todo a mp3 o wav
Tamaño por archivo 25 MB (según la documentación oficial) Divide si lo superas
Frecuencia de muestreo Sin requisito obligatorio 16 kHz en mono es suficiente
Duración Limitada indirectamente por el tamaño Divide audios largos en tramos de 10 minutos
Multicanal Se admite, pero la precisión es mediocre Mezcla primero o elige el canal principal

Un formato incorrecto devuelve un 400; un archivo demasiado grande suele devolver un 413. La transcodificación es el preprocesamiento más fiable.

7. Marcas de tiempo y formatos de salida

response_format Contenido devuelto Caso de uso
json Texto plano Solo necesitas el texto
text Texto plano con cuerpo de respuesta más simple Tuberías de scripts
srt Archivo de subtítulos Edición de vídeo
vtt Subtítulos web Reproductores web
verbose_json Texto, segmentos, idioma y duración Necesitas marcas de tiempo

Las marcas de tiempo por segmento se obtienen con timestamp_granularities=["segment"]; las marcas por palabra suelen estar disponibles solo para whisper-1 y requieren verbose_json. El soporte exacto depende de la documentación oficial o del sitio.

8. Cómo tratar audios largos

Para audios que superan el límite de tamaño, divídelos con ffmpeg y transcribe cada tramo:

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

Al dividir, ten en cuenta:

  1. Corta preferiblemente en silencios para no partir palabras por la mitad.
  2. Registra el desplazamiento inicial de cada tramo y vuelve a sumarlo a las marcas de tiempo al unir.
  3. Deja un solapamiento de 0,5–1 segundo entre tramos para reducir palabras perdidas en los bordes.
  4. Después de unir, elimina duplicados y ordena la puntuación.

9. Errores habituales

Error Causa Solución
401 Clave incorrecta o falta Bearer Revisa la clave y las cabeceras
404 Base URL o ruta incorrecta Confirma /v1/audio/transcriptions
400 unsupported file Formato no admitido Convierte a mp3 o wav
413 Archivo demasiado grande Comprime o divide
429 Se superó la frecuencia o la cuota Reduce la concurrencia y reintenta con espera
Texto vacío Silencio, volumen bajo o idioma mal detectado Revisa el audio y especifica language
Tiempo agotado Archivo grande o red lenta Divide y aumenta el tiempo máximo

10. Control de costes

  1. Haz detección de silencios antes de transcribir y elimina los tramos vacíos.
  2. Convierte todo a 16 kHz mono para reducir el tamaño del archivo.
  3. Divide los audios largos y procésalos en paralelo, pero controla la concurrencia para evitar errores 429.
  4. Prueba primero con una muestra corta para confirmar el idioma y la calidad, y luego envía por lotes.
  5. Registra la duración de audio de cada llamada y concilia por proyecto.
  6. Pon un límite a los reintentos para evitar cobros duplicados.

La transcripción de audio suele facturarse por minuto; el precio unitario figura en la página de precios de modelos del sitio. Barato no significa ahorrar: la conversión de formato, la revisión humana y los reintentos también suman al coste total.

11. Cómo mejorar la precisión

  1. Preprocesa el audio: conviértelo a 16 kHz mono, aplica una reducción de ruido ligera y elimina chasquidos y silencios largos.
  2. Especifica el idioma: para contenido en chino, pasa language=zh; si se mezclan chino e inglés, valora procesar por tramos.
  3. Aporta un prompt: usa el parámetro prompt para pasar nombres propios, nombres de personas y nombres de productos, y ayudar al modelo a alinear el vocabulario.
  4. Divide con criterio: corta en silencios, en tramos de 5–10 minutos, para evitar perder palabras entre segmentos.
  5. Revisa después: valida números, fechas, importes y nombres propios con reglas, y haz revisión humana en los casos críticos.
  6. Crea un glosario: reúne los errores frecuentes en una tabla de sustituciones y actualízala con cada versión.

No existe una cifra única de precisión: depende mucho de la calidad de la grabación, el acento y el vocabulario del dominio. Antes de salir a producción, haz una prueba por muestreo con audios reales de tu negocio; es más significativo que mirar parámetros promocionales.

12. Privacidad y cumplimiento

  • El audio puede contener nombres, teléfonos, direcciones, datos de salud y otra información personal; informa y obtén autorización antes de subirlo.
  • Anonimiza el contenido sensible o usa una solución que pueda desplegarse de forma privada.
  • Confirma la política de conservación, la estrategia de logs y el método de eliminación del proveedor.
  • No publiques en URL de acceso público audios con datos de clientes.
  • Evalúa la normativa local y los requisitos de cumplimiento de la empresa antes de transferir datos entre países.

Preguntas frecuentes

¿La API de Whisper admite chino?

Sí. Para transcribir chino se recomienda pasar language=zh explícitamente y complementar nombres propios en el prompt o en el posprocesado.

¿Puede una misma clave llamar también a modelos de texto?

En la pasarela normalmente sí, pero la disponibilidad de la interfaz de audio depende de la documentación del sitio; los permisos de una clave oficial también se configuran por cuenta y proyecto.

¿Se pueden devolver marcas de tiempo por palabra?

Algunos modelos y formatos lo permiten; suele requerir verbose_json y timestamp_granularities. Guíate por la documentación.

¿Qué hago si el audio supera los 25 MB?

Comprímelo con ffmpeg o divídelo en tramos de 10 minutos, transcribe cada uno y únelos. Elige puntos de corte en silencios siempre que sea posible.

¿Se puede usar comercialmente el resultado de la transcripción?

Depende de los derechos sobre el contenido del audio, los términos de la plataforma y la legislación local. Si implica grabaciones de terceros, música o contenido de cursos, confirma primero la autorización.

Siguiente paso

Primero regístrate en la pasarela de IA de ZSQH, crea una clave de prueba, ejecuta /v1/audio/transcriptions con un audio de un minuto y después intégralo en tu flujo por lotes. Los modelos y los precios figuran en precios de modelos.

Lecturas relacionadas: