En este tutorial, creamos un flujo de trabajo práctico avanzado con el SDK de Deepgram Python y exploramos cómo las capacidades modernas de inteligencia artificial de voz se combinan en un único entorno de Python. Configuramos la autenticación, conectamos clientes Deepgram sincrónicos y asincrónicos y trabajamos directamente con datos de audio reales para comprender cómo el SDK maneja la transcripción, la generación de voz y el análisis de texto en la práctica. Transcribimos audio tanto de una URL como de un archivo local, inspeccionamos puntuaciones de confianza, marcas de tiempo a nivel de palabra, diarios de los oradores, formato de párrafos y resúmenes generados por IA, y luego ampliamos el proceso al procesamiento asíncrono para una ejecución más rápida y escalable. También generamos voz con múltiples voces TTS, analizamos el texto en busca de opiniones, temas e intenciones, y examinamos controles de transcripción avanzados, como búsqueda de palabras clave, reemplazo, mejora, acceso a respuestas sin procesar y manejo estructurado de errores. A través de este proceso, creamos un flujo de trabajo de IA de voz de Deepgram práctico e integral que es técnicamente detallado y fácil de adaptar a aplicaciones del mundo real.
!pip install deepgram-sdk httpx –quiet import os, asyncio, textwrap, urllib.request from getpass import getpass from deepgram import DeepgramClient, AsyncDeepgramClient from deepgram.core.api_error import ApiError from IPython.display import Audio, display DEEPGRAM_API_KEY = getpass("🔑 Ingrese su clave API de Deepgram: ") os.environ["DEEPGRAM_API_KEY"] = DEEPGRAM_API_KEY cliente = DeepgramClient(api_key=DEEPGRAM_API_KEY) async_client = AsyncDeepgramClient(api_key=DEEPGRAM_API_KEY) AUDIO_URL = "https://dpgr.am/spacewalk.wav" AUDIO_PATH = "/tmp/sample.wav" urllib.request.urlretrieve(AUDIO_URL, AUDIO_PATH) def read_audio(path=AUDIO_PATH): con open(path, "rb") as f: return f.read() def _get(obj, key, default=None): """Obtiene un campo de un dict o de un objeto; v6 devuelve ambos.""" if isinstance(obj, dict): return obj.get(key, default) return getattr(obj, key, default) def get_model_name(meta): mi = _get(meta, "model_info") si mi es Ninguno: return "n/a" return _get(mi, "name", "n/a") def tts_to_bytes(response) -> bytes: """v6 generate() devuelve un generador de fragmentos o un objeto con .stream.""" if hasattr(response, "stream"): return respuesta.stream.getvalue() return b"".join(fragmento por fragmento en respuesta si isinstance(fragmento, bytes)) def save_tts(respuesta, ruta: str) -> str: con open(ruta, "wb") as f: f.write(tts_to_bytes(respuesta)) ruta de retorno print("✅ Cliente Deepgram listo | audio de muestra descargado") print("n" + "="*60) print("📼 SECCIÓN 2: Transcripción pregrabada desde URL") print("="*60) respuesta = client.listen.v1.media.transcribe_url( url=AUDIO_URL, model="nova-3", smart_format=True, diarize=True, language="en", utterances=True, filler_words=True, ) transcript = respuesta.results.channels[0].alternativas[0].transcript print(f"n📝 Transcripción completa:n{textwrap.fill(transcript, 80)}") confianza = respuesta.resultados.canales[0].alternativas[0].confidence print(f"n🎯 Confianza: {confianza:.2%}") palabras = respuesta.resultados.canales[0].alternativas[0].words print(f"n🔤 Primeras 5 palabras con sincronización:") for w en palabras[:5]: print(f" '{w.word}' start={w.start:.2f}s end={w.end:.2f}s conf={w.confidence:.2f}") print(f"n👥 Diarización del orador (primeras 5 palabras):") for w en palabras[:5]: orador = getattr(w, "speaker", Ninguno) si el hablante no es Ninguno: print(f" Speaker {int(speaker)}: '{w.word}'") meta = respuesta.metadata print(f"n📊 Metadatos: duración={meta.duration:.2f}s canales={int(meta.channels)} model={get_model_name(meta)}")
Instalamos el SDK de Deepgram y sus dependencias, luego configuramos de forma segura la autenticación utilizando nuestra clave API. Inicializamos clientes Deepgram sincrónicos y asincrónicos, descargamos un archivo de audio de muestra y definimos funciones auxiliares para facilitar el trabajo con objetos de respuesta mixtos, bytes de audio, metadatos de modelos y salidas TTS transmitidas. Luego ejecutamos nuestra primera transcripción pregrabada desde una URL e inspeccionamos la transcripción, la puntuación de confianza, las marcas de tiempo a nivel de palabra, el diario del hablante y los metadatos para comprender la estructura y la riqueza de la respuesta.
print("n" + "="*60) print("📂 SECCIÓN 3: Transcripción pregrabada de un archivo") print("="*60) file_response = client.listen.v1.media.transcribe_file( request=read_audio(), model="nova-3", smart_format=True, diarize=True, parrafos=True, resume="v2", ) alt = archivo_respuesta.resultados.canales[0].alternativas[0]parrafos = getattr(alt, "paragraphs", Ninguno) if parrafos y _get(paragraphs, "paragraphs"): print("n📄 Transcripción con formato de párrafo:") for para in _get(paragraphs, "paragraphs")[:2]: oraciones = " ".join(_get(s, "text", "") for s in (_get(para, "sentences") o[])) print(f" [Hablador {int(_get(para,'speaker',0))}, " f"{_get(para,'start',0):.1f}s–{_get(para,'end',0):.1f}s] {frases[:120]}…") else: print(f"n📝 Transcripción: {alt.transcript[:200]}…") if getattr(file_response.results, "summary", Ninguno): short = _get(file_response.results.summary, "short", "") if short: print(f"n📌 Resumen AI: {short}") print(f"n🎯 Confianza: {alt.confidence:.2%}") print(f"🔤 Número de palabras: {len(alt.words)}") print("n" + "="*60) print("⚡ SECCIÓN 4: Transcripción paralela asíncrona") print("="*60) async def transcribe_async(): audio_bytes = read_audio() async def from_url(label): r = await async_client.listen.v1.media.transcribe_url( url=AUDIO_URL, model="nova-3", smart_format=Verdadero, ) print(f" [{label}] {r.results.channels[0].alternativas[0].transcript[:100]}…") async def from_file(label): r = await async_client.listen.v1.media.transcribe_file( request=audio_bytes, model="nova-3", smart_format=True, ) print(f" [{label}] {r.results.channels[0].alternativas[0].transcript[:100]}…") espera asyncio.gather(from_url("Desde URL"), from_file("Desde archivo")) espera transcribe_async()
Pasamos de la transcripción basada en URL a la basada en archivos enviando bytes de audio sin procesar directamente a la API de Deepgram, lo que permite opciones más ricas, como párrafos y resúmenes. Inspeccionamos la estructura de párrafos devueltos, la segmentación de los hablantes, el resultado del resumen, la puntuación de confianza y el recuento de palabras para ver cómo el SDK admite resultados de transcripción más legibles y fáciles de analizar. También introducimos el procesamiento asincrónico y ejecutamos transcripciones basadas en archivos y URL en paralelo, lo que nos ayuda a comprender cómo construir canales de inteligencia artificial de voz más rápidos y escalables.
print("n" + "="*60) print("🔊 SECCIÓN 5: Texto a voz") print("="*60) sample_text = ( "Bienvenido al tutorial avanzado de Deepgram. " "Este SDK le permite transcribir audio, " "generar voz y analizar texto, todo con una sencilla interfaz de Python." ) tts_path = save_tts( client.speak.v1.audio.generate(text=sample_text, model="aura-2-asteria-en"), "/tmp/tts_output.mp3", ) size_kb = os.path.getsize(tts_path) / 1024 print(f"✅ Audio TTS guardado → {tts_path} ({size_kb:.1f} KB)") display(Audio(tts_path)) print("n" + "="*60) print("🎭 SECCIÓN 6: Comparación de múltiples voces TTS") print("="*60) voices = { "aura-2-asteria-en": "Asteria (femenina, cálida)", "aura-2-orion-en": "Orion (masculino, profundo)", "aura-2-luna-en": "Luna (femenina, brillante)", } para model_id, etiqueta en voices.items(): intente: ruta = save_tts( client.speak.v1.audio.generate(text="¡Hola! Soy un modelo de voz de Deepgram.", model=model_id), f"/tmp/tts_{model_id}.mp3", ) print(f" ✅ {label}") display(Audio(path)) excepto Excepción como e: print(f" ⚠️ {label} — {e}") print("n" + "="*60) print("🧠 SECCIÓN 7: Inteligencia de texto: sentimiento, temas, intenciones") print("="*60) review_text = ( "¡Me encanta este producto! Llegó rápidamente, la calidad es " "excelente y la atención al cliente fue increíblemente útil cuando " "tuve una pregunta. Definitivamente lo recomendaría a cualquiera que " "busque una solución confiable. ¡Cinco estrellas!" ) read_response = client.read.v1.text.analyze( request={"text": review_text}, language="en", sentimiento=Verdadero, temas=Verdadero, intenciones=Verdadero, resumir=Verdadero,) resultados = read_response.results
Nos centramos en la generación de voz convirtiendo texto en audio utilizando la API de texto a voz de Deepgram y guardando el audio resultante como un archivo MP3. Luego comparamos varias voces TTS para escuchar cómo se comportan los diferentes modelos de voz y con qué facilidad podemos cambiar entre ellos manteniendo el mismo patrón de código. Después de eso, comenzamos a trabajar con la API de lectura pasando el texto de revisión al sistema de inteligencia de texto de Deepgram para analizar el lenguaje más allá de la simple transcripción.
if getattr(resultados, "sentimentos", Ninguno): global = resultados.sentimentos.promedio print(f"😊 Sentimiento: {_get(general,'sentiment','?').upper()} " f"(score={_get(overall,'sentiment_score',0):.3f})") para seg en (_get(results.sentiments, "segmentos") o[])[:2]: print(f" • "{_get(seg,'text','')[:60]}" → {_get(seg,'sentiment','?')}") if getattr(resultados, "topics", Ninguno): print(f"n🏷️ Temas detectados:") para seg en (_get(results.topics, "segments") o[])[:3]: para t en (_get(seg, "temas") o[]): print(f" • {_get(t,'topic','?')} (conf={_get(t,'confidence_score',0):.2f})") if getattr(resultados, "intents", Ninguno): print(f"n🎯 Intenciones detectadas:") para seg in (_get(results.intents, "segments") o[])[:3]: para intención en (_get(seg, "intentos") o[]): print(f" • {_get(intent,'intent','?')} (conf={_get(intent,'confidence_score',0):.2f})") if getattr(resultados, "resumen", Ninguno): texto = _get(resultados.summary, "text", "") if text: print(f"n📌 Resumen: {texto}") print("n" + "="*60) print("⚙️ SECCIÓN 8: Opciones avanzadas: Buscar, reemplazar, impulsar") print("="*60) search_response = client.listen.v1.media.transcribe_url( url=AUDIO_URL, model="nova-3", smart_format=True, punctuate=True, search=["spacewalk", "mission", "astronaut"], replace=[{"find": "um", "reemplazar": "[vacilación]"}], término clave=["paseo espacial", "NASA"], ) ch = search_response.results.channels[0]if getattr(ch, "search", Ninguno): print("🔍 Resultados de la búsqueda por palabra clave:") para hit_group en ch.search: hits = _get(hit_group, "hits") o[]print(f" '{_get(hit_group,'query','?')}': {len(hits)} hit(s)") para h en hits[:2]: print(f" en {_get(h,'start',0):.2f}s–{_get(h,'end',0):.2f}s " f"conf={_get(h,'confidence',0):.2f}") print(f"n📝 Transcripción:n{textwrap.fill(ch.alternatives[0].transcript, 80)}") print("n" + "="*60) print("🔩 SECCIÓN 9: Acceso a respuesta HTTP sin formato") print("="*60) raw = client.listen.v1.media.with_raw_response.transcribe_url( url=AUDIO_URL, model="nova-3", ) print(f"Tipo de respuesta: {type(raw.data).__name__}") request_id = raw.headers.get("dg-request-id", raw.headers.get("x-dg-request-id", "n/a")) print(f"ID de solicitud: {request_id}")
Continuamos con la inteligencia de texto e inspeccionamos opiniones, temas, intenciones y resultados resumidos del texto analizado para comprender cómo Deepgram estructura los conocimientos del lenguaje de nivel superior. Luego exploramos opciones de transcripción avanzadas, como términos de búsqueda, reemplazo de palabras y mejora de términos clave, para hacer que la transcripción sea más específica y útil para aplicaciones de dominios específicos. Finalmente, accedemos a la respuesta HTTP sin procesar y a los encabezados de solicitud, lo que proporciona una vista de nivel inferior de la interacción API y facilita la depuración y la observabilidad.
print("n" + "="*60) print("🛡️ SECCIÓN 10: Manejo de errores") print("="*60) def safe_transcribe(url: str, model: str = "nova-3"): try: r = client.listen.v1.media.transcribe_url( url=url, model=model, request_options={"timeout_in_segundos": 30, "max_retries": 2},) devuelve r.results.channels[0].alternativas[0].transcript excepto ApiError como e: print(f" ❌ ApiError {e.status_code}: {e.body}") return Ninguno excepto Excepción como e: print(f" ❌ {type(e).__name__}: {e}") return Ninguno t = safe_transcribe(AUDIO_URL) print(f"✅ URL válida → '{t[:60]}….'") t_bad = safe_transcribe("https://example.com/nonexistent_audio.wav") si t_bad es Ninguno: print("✅ URL no válida → error detectado correctamente") print("n" + "="*60) print("🎉 ¡Tutorial completo! Secciones cubiertas:") for s in [ "2. transcribe_url(url=…) + diarización + sincronización de palabras", "3. transcribe_file(request=bytes) + párrafos + resumen", "4. Transcripción paralela asíncrona", "5. Texto a voz: seguro para generador mediante save_tts()", "6. Comparación de TTS de varias voces", "7. Inteligencia de texto: sentimiento, temas, intenciones (seguro para dictados)", "8. Opciones avanzadas: búsqueda de palabras clave, reemplazo de palabras, identificación de solicitud", "10. imprimir("="*60)
Creamos un contenedor de transcripción seguro que agrega controles de tiempo de espera y reintento mientras maneja con elegancia las excepciones generales y específicas de API. Probamos la función con una URL de audio válida y otra no válida para confirmar que nuestro flujo de trabajo se comporta de manera confiable incluso cuando las solicitudes fallan. Finalizamos el tutorial imprimiendo un resumen completo de todas las secciones cubiertas, lo que nos ayuda a revisar el proceso completo de Deepgram, desde la transcripción y TTS hasta la inteligencia de texto, opciones avanzadas, respuestas sin procesar y manejo de errores.
En conclusión, establecimos una comprensión completa y práctica de cómo utilizar el SDK de Deepgram Python para flujos de trabajo avanzados de voz y lenguaje. Realizamos transcripción de alta calidad y generación de texto a voz, y también aprendimos a extraer un valor más profundo del audio y el texto mediante inspección de metadatos, resúmenes, análisis de opiniones, detección de temas, reconocimiento de intenciones, ejecución asíncrona y depuración a nivel de solicitud. Esto hace que el tutorial sea mucho más que un recorrido básico del SDK, porque conectamos activamente múltiples capacidades en un canal unificado que refleja cómo a menudo se construyen los sistemas de inteligencia artificial de voz listos para producción. Además, vimos cómo el SDK admite tanto la facilidad de uso como el control avanzado, lo que nos permite pasar de ejemplos simples a implementaciones más ricas y resistentes. Al final, obtuvimos una base sólida para crear herramientas de transcripción, interfaces de voz, sistemas de inteligencia de audio y otras aplicaciones del mundo real impulsadas por Deepgram.
Consulte los códigos completos aquí. Además, no dude en seguirnos en Twitter y no olvide unirse a nuestro SubReddit de más de 130.000 ML y suscribirse a nuestro boletín. ¡Esperar! estas en telegrama? Ahora también puedes unirte a nosotros en Telegram.
¿Necesita asociarse con nosotros para promocionar su repositorio de GitHub O su página principal de Hugging O su lanzamiento de producto O seminario web, etc.? Conéctate con nosotros
