---
id: INT-009
type: Integration
title: "Transcripción de audio"
provider: "OpenAI Whisper"
status: Pendiente
integration_type: "Speech-to-Text"
created_at: 2026-01-10
updated_at: 2026-01-10
simco_version: "3.8.0"
tags:
  - audio
  - transcripcion
  - whisper
  - openai
  - speech-to-text
  - whatsapp
---

# INT-009: Transcripción de audio

## Metadata

| Campo | Valor |
|-------|-------|
| **Codigo** | INT-009 |
| **Proveedor** | OpenAI Whisper |
| **Tipo** | Speech-to-Text |
| **Estado** | Pendiente |
| **Multi-tenant** | Si |
| **Fecha planeada** | 2026-Q1 |
| **Owner** | Backend Team |

---

## 1. Descripcion

Integración con OpenAI Whisper API para transcripción automática de mensajes de voz. Permite convertir los audios recibidos por WhatsApp en texto, facilitando el procesamiento automático de pedidos por voz y mejorando la experiencia del cliente que prefiere enviar notas de voz en lugar de escribir.

**Casos de uso principales:**
- Transcripción de mensajes de voz de WhatsApp de clientes
- Procesamiento de pedidos dictados por voz
- Generación de registros de conversaciones por audio
- Búsqueda de contenido en mensajes de voz históricos
- Accesibilidad para usuarios con dificultades de lectura

---

## 2. Credenciales Requeridas

### Variables de Entorno

| Variable | Descripcion | Tipo | Obligatorio |
|----------|-------------|------|-------------|
| OPENAI_API_KEY | API key de OpenAI | string | SI |
| WHISPER_MODEL | Modelo a usar (whisper-1) | string | SI |
| WHISPER_LANGUAGE | Idioma por defecto (es) | string | NO |
| WHISPER_RESPONSE_FORMAT | Formato de respuesta (json, text, srt, vtt) | string | NO |
| OPENAI_ORG_ID | ID de organización OpenAI (opcional) | string | NO |

### Ejemplo de .env

```env
# OpenAI Whisper Transcription
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
WHISPER_MODEL=whisper-1
WHISPER_LANGUAGE=es
WHISPER_RESPONSE_FORMAT=json
OPENAI_ORG_ID=org-xxxxxxxxxxxxxxxx
```

---

## 3. Arquitectura

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           MiChangarrito                                 │
│  ┌────────────────┐    ┌──────────────┐    ┌────────────────────────┐  │
│  │  WhatsApp      │───▶│  Message     │───▶│   WhisperService       │  │
│  │  Webhook       │    │  Processor   │    │                        │  │
│  │  (Audio msg)   │    │              │    │  - Download audio      │  │
│  └────────────────┘    └──────────────┘    │  - Convert format      │  │
│                                            │  - Transcribe          │  │
│                                            │  - Parse intent        │  │
│                                            └───────────┬────────────┘  │
└────────────────────────────────────────────────────────┼───────────────┘
                                                         │
                               ┌─────────────────────────┴─────────────────┐
                               │                                           │
                               ▼                                           ▼
                    ┌──────────────────┐                        ┌──────────────────┐
                    │   OpenAI API     │                        │   LLM Service    │
                    │   Whisper        │                        │   (Intent/NER)   │
                    │                  │                        │                  │
                    │  Audio → Texto   │                        │  Texto → Pedido  │
                    └──────────────────┘                        └──────────────────┘
```

### Flujo de Procesamiento de Audio

1. Cliente envía nota de voz por WhatsApp
2. Webhook recibe mensaje con media_id del audio
3. Sistema descarga archivo de audio de WhatsApp
4. Audio se convierte a formato compatible (mp3/wav)
5. WhisperService envía audio a OpenAI Whisper API
6. API retorna transcripción en español
7. Texto se procesa con LLM para extraer intención
8. Si es pedido, se extrae productos y cantidades
9. Se responde al cliente confirmando pedido

---

## 4. Endpoints

### Endpoints Consumidos (OpenAI Whisper API)

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | `/v1/audio/transcriptions` | Transcribir audio a texto |
| POST | `/v1/audio/translations` | Transcribir y traducir a inglés |

### Parámetros de Request

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `file` | file | Archivo de audio (mp3, wav, m4a, etc.) |
| `model` | string | Modelo: "whisper-1" |
| `language` | string | Código ISO-639-1 (ej: "es") |
| `response_format` | string | json, text, srt, verbose_json, vtt |
| `temperature` | float | 0-1, mayor = más creativo |
| `prompt` | string | Contexto para mejorar precisión |

### Endpoints Expuestos (MiChangarrito)

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | `/api/v1/audio/transcribe` | Transcribir audio subido |
| POST | `/api/v1/audio/transcribe-url` | Transcribir desde URL |
| GET | `/api/v1/audio/transcriptions/{id}` | Obtener transcripción |
| GET | `/api/v1/audio/transcriptions` | Listar transcripciones |

---

## 5. Notas de Implementacion

- Whisper soporta: mp3, mp4, mpeg, mpga, m4a, wav, webm
- Tamaño máximo de archivo: 25MB
- Para audios largos, segmentar en chunks de ~10 minutos
- Usar `language: "es"` para mejor precisión en español mexicano
- El prompt puede incluir términos del dominio (productos del changarro)
- Costo aproximado: $0.006 USD por minuto de audio
- Implementar cola para procesar audios en background
- Guardar transcripciones para evitar reprocesar
- WhatsApp envía audios en formato OGG/Opus, convertir a mp3
- Usar ffmpeg para conversión de formatos
- Implementar fallback si Whisper falla (mensaje de error al usuario)
- Considerar modelo Whisper local para reducir costos a largo plazo
- Manejar rate limits: 50 RPM para whisper-1
- La transcripción incluye timestamps en formato verbose_json
- Implementar detección de idioma automática para clientes no hispanohablantes