Envía el video desde tu código
Crea una clave de API en el panel y úsala desde tu servidor o script. Envía la URL por POST con Python o cualquier cliente HTTP. Con wait=60 esperamos hasta 60 segundos antes de responder. Los campos y códigos de respuesta están en la referencia de creación.
Guarda el ID en cuanto recibas la respuesta. Si la transcripción sigue en curso, consulta GET /v1/transcriptions/:id. Que termine la espera del request no significa que haya fallado: el trabajo continúa. No envíes otro POST para comprobarlo.
Tu código debe distinguir queued, fetching y transcribing de los estados finales. Cuando llegue completed, lee la transcripción; si llega failed, maneja el error. Un video inaccesible o una demora de red no deberían mostrarse como una transcripción vacía que supuestamente salió bien.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'Consulta transcript_source antes de usar el texto
La respuesta indica si usamos subtítulos y si los subió el creador o los generó YouTube. billed_minutes muestra la duración redondeada hacia arriba. Puedes consultar todos los campos del objeto de transcripción.
Conserva transcript_source y caption_kind si necesitas registrar la procedencia. Los subtítulos del creador mantienen su redacción y no incluyen tiempos por palabra. Los generados automáticamente por YouTube sí incluyen el inicio de cada palabra. La transcripción con IA añade inicio, fin y confianza.
Cada segmento también tiene inicio y fin en segundos. Úsalos para saltar al pasaje citado, alinear notas con el reproductor o dar contexto a un asistente. Pide include=words solo si necesitas ese detalle. El JSON de abajo ilustra los campos; no reproduce las palabras del video del ejemplo.
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}Usa subtítulos o transcribe el audio con IA
source=auto es la opción predeterminada. Elige captions (solo subtítulos) si necesitas la pista publicada: si no existe una utilizable, recibes no_captions y no pagas. Con stt siempre transcribimos el audio. Consulta cómo combinar estas opciones en la guía de fuentes.
Para una transcripción nueva del audio o para identificar hablantes, usa speech-to-text. Si envías diarize=true con auto, omitimos los subtítulos. No puedes combinar diarize=true con captions: rechazamos el request en vez de ignorar una de las opciones.
La pista debe coincidir con el idioma que pediste; si dejaste el idioma en auto, buscamos el original del video. No usamos pistas traducidas automáticamente. Indicar un idioma para speech-to-text ayuda al reconocimiento, pero no traduce la grabación.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}Revisa el error antes de volver a enviar el video
Un video privado, una restricción de edad o una transmisión que sigue en vivo requieren otra fuente. Reintentar el mismo enlace no cambia su acceso. Si recibes no_captions, decide si te sirve transcribir el audio. Si todavía se está procesando, consulta el ID que ya tienes. La guía de errores te ayuda a decidir.
Cuando necesites repetir un request de creación por un problema de conexión, sigue el contrato de Idempotency-Key. Reutilizar una transcripción reciente es otra opción: busca el mismo video con las mismas opciones. Que el texto esté en caché no implica que un trabajo nuevo sea gratis; leer una transcripción ya terminada sí consume cero minutos.
La misma API también acepta videos de TikTok, Reels de Instagram y otras fuentes. YouTube, X, TikTok y Bluesky, por ejemplo, pueden aportar subtítulos antes de recurrir al audio. Consulta las combinaciones válidas en la guía de fuentes y opciones antes de ofrecerlas en tu aplicación.