For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Transcribe un archivo de audio o vídeo. Si webhook se establece en true, la solicitud se procesará de forma asíncrona y los resultados se enviarán a los webhooks configurados. Cuando use_multi_channel es true y el audio proporcionado tiene varios canales, se devuelve un objeto 'transcripts' con transcripciones independientes para cada canal; establece multichannel_output_style='combined' para recibir una única transcripción con todos los canales combinados y ordenados por tiempo. De lo contrario, se devuelve una única transcripción. El parámetro opcional webhook_metadata te permite adjuntar datos personalizados que se incluirán en las respuestas de los webhooks para correlacionar y rastrear solicitudes.
Encabezados
xi-api-keystringOpcional
Parámetros de consulta
tokenstring or nullOpcional
Un token de autenticación de un solo uso creado mediante POST /v1/single-use-token/batch_scribe. Este token solo puede usarse una vez y caduca tras 15 minutos. Es una alternativa a la autenticación mediante clave de API o token bearer para clientes de frontend.
When enable_logging is set to false zero retention mode will be used for the request. This will mean log and transcript storage features are unavailable for this request. Zero retention mode may only be used by enterprise customers.
Solicitud
This endpoint expects a multipart form containing an optional file.
model_idstringRequerido
El ID del modelo que se usará para la transcripción.
filefileOpcional
El archivo que se va a transcribir (duración mínima de audio de 100 ms). Se admiten todos los formatos de audio y vídeo principales. Debes proporcionar exactamente uno de los parámetros file o cloud_storage_url. El tamaño del archivo debe ser inferior a 5,0 GB.
language_codestring or nullOpcional
Un language_code ISO-639-1 o ISO-639-3 correspondiente al idioma del archivo de audio. A veces puede mejorar el rendimiento de la transcripción si se conoce de antemano. El valor predeterminado es null; en ese caso, el idioma se predice automáticamente.
transcript_editstring or nullOpcional
Instrucción en lenguaje natural aplicada a la transcripción final (máximo 2000 caracteres). El texto editado se devuelve en 'edited_transcript' junto con la transcripción original. No se puede combinar con entity_detection, entity_redaction ni use_multi_channel. El uso de este parámetro supondrá un recargo adicional del 30 % sobre el coste base de transcripción, facturado por al menos 10 segundos de audio.
Si se etiquetan eventos de audio como (risas), (pasos), etc. en la transcripción.
num_speakersinteger or nullOpcional1-32
El número máximo de hablantes que intervienen en el archivo subido. Puede ayudar a predecir quién habla en cada momento. El número máximo de hablantes que se puede predecir es 32. El valor predeterminado es null; en ese caso, el número de hablantes se establece en el valor máximo compatible con el modelo.
timestamps_granularityenumOpcionalValor predeterminado: word
La granularidad de las marcas de tiempo en la transcripción. «word» proporciona marcas de tiempo a nivel de palabra y «character» proporciona marcas de tiempo a nivel de carácter por palabra.
Valores permitidos:
diarizebooleanOpcionalValor predeterminado: false
Indica si se debe anotar qué hablante está hablando en cada momento en el archivo subido.
diarization_thresholddouble or nullOpcional0.1-0.4
Umbral de diarización que se aplicará durante la diarización de hablantes. Un valor más alto implica una menor probabilidad de que un hablante se diarice como dos hablantes distintos, pero también una mayor probabilidad de que dos hablantes distintos se diaricen como uno solo (se predecirán menos hablantes en total). Un valor bajo implica una mayor probabilidad de que un hablante se diarice como dos hablantes distintos, pero también una menor probabilidad de que dos hablantes distintos se diaricen como uno solo (se predecirán más hablantes en total). Solo se puede establecer cuando diarize=True y num_speakers=None. El valor predeterminado es None; en ese caso, elegiremos un umbral basado en model_id (normalmente, 0.22).
additional_formatslist of objectsOpcional
Una lista de formatos adicionales a los que exportar la transcripción.
file_formatenumOpcionalValor predeterminado: other
The format of input audio. Options are ‘pcm_s16le_16’ or ‘other’ For pcm_s16le_16, the input audio must be 16-bit PCM at a 16kHz sample rate, single channel (mono), and little-endian byte order. Latency will be lower than with passing an encoded waveform.
Valores permitidos:
cloud_storage_urlstring or nullOpcionalDeprecated
[Obsoleto] Este parámetro está obsoleto y se eliminará en el futuro. Usa 'source_url' en su lugar. La URL HTTPS del archivo que se va a transcribir. Debe proporcionarse exactamente uno de los parámetros file o cloud_storage_url. El archivo debe ser accesible mediante HTTPS y su tamaño debe ser inferior a 2 GB. Se acepta cualquier URL HTTPS válida, incluidas URL de proveedores de almacenamiento en la nube (AWS S3, Google Cloud Storage, Cloudflare R2, etc.), CDN u otra fuente HTTPS. Las URL pueden estar prefirmadas o incluir tokens de autenticación en los parámetros de consulta.
source_urlstring or nullOpcional
La URL de un archivo de audio o vídeo que se transcribirá. Admite archivos de vídeo o audio alojados, URL de vídeos de YouTube, URL de vídeos de TikTok y otros servicios de alojamiento de vídeos.
webhookbooleanOpcionalValor predeterminado: false
Si se envía el resultado de la transcripción a los webhooks de Voz a Texto configurados. Si se configura, la solicitud devolverá una respuesta anticipada sin la transcripción, que se entregará más tarde mediante webhook.
webhook_idstring or nullOpcional
ID opcional de un webhook específico al que enviar el resultado de la transcripción. Solo es válido cuando webhook está establecido en true. Si no se proporciona, la transcripción se enviará a todos los webhooks de voz a texto configurados.
temperaturedouble or nullOpcional0-2
Controla la aleatoriedad del resultado de la transcripción. Acepta valores entre 0.0 y 2.0; los valores más altos producen resultados más diversos y menos deterministas. Si se omite, usaremos una temperatura basada en el modelo que hayas seleccionado, que normalmente es 0.
seedinteger or nullOpcional0-2147483647
Si se especifica, nuestro sistema hará todo lo posible para realizar el muestreo de forma determinista, de modo que las solicitudes repetidas con la misma semilla y parámetros deberían devolver el mismo resultado. No se garantiza el determinismo. Debe ser un número entero entre 0 y 2147483647.
Indica si el archivo de audio contiene varios canales, cada uno con un único hablante. Cuando está activado, cada canal se transcribe de forma independiente. De forma predeterminada, se devuelve una transcripción independiente por canal; configura multichannel_output_style='combined' para recibir una única transcripción con todos los canales combinados y ordenados por tiempo. Cada palabra de la respuesta incluye un campo 'channel_index' que indica en qué canal se pronunció. Se admite un máximo de 5 canales. Cada canal se factura de forma independiente por la duración completa del audio, por lo que el coste aumenta linealmente con el número de canales.
multichannel_output_styleenumOpcionalValor predeterminado: separate
Controla la estructura de la respuesta cuando use_multi_channel está activado. 'separate' (predeterminado) devuelve una transcripción por canal en 'transcripts'. 'combined' combina todos los canales en una única transcripción cuyas palabras se ordenan por hora de inicio, cada una con un 'channel_index', siguiendo la estructura de respuesta de un solo canal. 'combined' requiere marcas de tiempo (timestamps_granularity no puede ser 'none') y no admite la detección ni la redacción de entidades.
Valores permitidos:
webhook_metadatastring or map from strings to any or nullOpcional
Metadatos opcionales que se incluirán en la respuesta del webhook. Deben ser una cadena JSON que represente un objeto con una profundidad máxima de 2 niveles y un tamaño máximo de 16 KB. Resulta útil para realizar el seguimiento de ID internos, referencias de tareas u otra información contextual.
entity_detectionstring or list of strings or nullOpcional
Detecta entidades en la transcripción. Puede ser 'all' para detectar todas las entidades, una cadena de texto con un único tipo o categoría de entidad, o una lista de tipos o categorías de entidades. Las categorías incluyen 'pii', 'phi', 'pci', 'other' y 'offensive_language'. Cuando está activado, las entidades detectadas se devolverán en el campo 'entities' con su texto, tipo y posiciones de caracteres. El uso de este parámetro conlleva un recargo adicional del 30 % sobre el coste base de la transcripción.
Si se usa la biblioteca de hablantes para identificar hablantes conocidos durante la diarización. Cuando está activada y diarize es true, los hablantes detectados se comparan con los hablantes registrados en la biblioteca de hablantes del espacio de trabajo.
Indica si se deben detectar los roles de los hablantes (agente frente a cliente). Requiere diarize=true. No se puede usar con use_multi_channel=true. Cuando está activado, los valores de speaker_id serán 'agent' y 'customer' en lugar de 'speaker_0', 'speaker_1', etc. Su uso conlleva un recargo adicional del 10 % sobre el coste base de transcripción.
entity_redactionstring or list of strings or nullOpcional
Oculta entidades del texto de la transcripción. Acepta el mismo formato que entity_detection: 'all', una categoría ('pii', 'phi') o tipos de entidad específicos. Debe ser un subconjunto de entity_detection. Cuando la ocultación está activada, no se devolverá el campo entities. El uso de este parámetro conlleva un recargo adicional del 30 % sobre el coste base de la transcripción.
Cómo dar formato a las entidades ocultadas. ‘redacted’ sustituye por {REDACTED}, ‘entity_type’ sustituye por {ENTITY_TYPE} y ‘enumerated_entity_type’ sustituye por {ENTITY_TYPE_N}, donde N enumera cada aparición. Solo se utiliza cuando entity_redaction está establecido.
keytermslist of stringsOpcionalValor predeterminado: []
Una lista de términos clave para orientar la transcripción hacia ellos. Los términos clave son palabras o frases que quieres que el modelo reconozca con mayor precisión. El número de términos clave no puede superar los 1000. La longitud de cada término clave debe ser inferior a 50 caracteres. Los términos clave pueden contener como máximo 5 palabras (tras la normalización). Por ejemplo, ["hello", "world", "technical term"]. No se admiten los siguientes caracteres: `<`, `>`, `{`, `}`, `[`, `]`, `\`. El uso de este parámetro conlleva un recargo adicional del 20 % sobre el coste base de la transcripción. Cuando se proporcionan más de 100 términos clave, se aplica una duración mínima facturable de 20 segundos por solicitud.
Respuesta
Resultado de transcripción síncrona.
SpeechToTextChunkResponseModelobject
Detalle de la transcripción por fragmentos con información de tiempo.
OR
MultichannelSpeechToTextResponseModelobject
Modelo de respuesta para la transcripción de voz a texto multicanal.
Transcribe un archivo de audio o vídeo. Si webhook se establece en true, la solicitud se procesará de forma asíncrona y los resultados se enviarán a los webhooks configurados. Cuando use_multi_channel es true y el audio proporcionado tiene varios canales, se devuelve un objeto ‘transcripts’ con transcripciones independientes para cada canal; establece multichannel_output_style=‘combined’ para recibir una única transcripción con todos los canales combinados y ordenados por tiempo. De lo contrario, se devuelve una única transcripción. El parámetro opcional webhook_metadata te permite adjuntar datos personalizados que se incluirán en las respuestas de los webhooks para correlacionar y rastrear solicitudes.
Instrucción en lenguaje natural aplicada a la transcripción final (máximo 2000 caracteres). El texto editado se devuelve en ‘edited_transcript’ junto con la transcripción original. No se puede combinar con entity_detection, entity_redaction ni use_multi_channel. El uso de este parámetro supondrá un recargo adicional del 30 % sobre el coste base de transcripción, facturado por al menos 10 segundos de audio.
Umbral de diarización que se aplicará durante la diarización de hablantes. Un valor más alto implica una menor probabilidad de que un hablante se diarice como dos hablantes distintos, pero también una mayor probabilidad de que dos hablantes distintos se diaricen como uno solo (se predecirán menos hablantes en total). Un valor bajo implica una mayor probabilidad de que un hablante se diarice como dos hablantes distintos, pero también una menor probabilidad de que dos hablantes distintos se diaricen como uno solo (se predecirán más hablantes en total). Solo se puede establecer cuando diarize=True y num_speakers=None. El valor predeterminado es None; en ese caso, elegiremos un umbral basado en model_id (normalmente, 0.22).
[Obsoleto] Este parámetro está obsoleto y se eliminará en el futuro. Usa ‘source_url’ en su lugar. La URL HTTPS del archivo que se va a transcribir. Debe proporcionarse exactamente uno de los parámetros file o cloud_storage_url. El archivo debe ser accesible mediante HTTPS y su tamaño debe ser inferior a 2 GB. Se acepta cualquier URL HTTPS válida, incluidas URL de proveedores de almacenamiento en la nube (AWS S3, Google Cloud Storage, Cloudflare R2, etc.), CDN u otra fuente HTTPS. Las URL pueden estar prefirmadas o incluir tokens de autenticación en los parámetros de consulta.
Indica si el archivo de audio contiene varios canales, cada uno con un único hablante. Cuando está activado, cada canal se transcribe de forma independiente. De forma predeterminada, se devuelve una transcripción independiente por canal; configura multichannel_output_style=‘combined’ para recibir una única transcripción con todos los canales combinados y ordenados por tiempo. Cada palabra de la respuesta incluye un campo ‘channel_index’ que indica en qué canal se pronunció. Se admite un máximo de 5 canales. Cada canal se factura de forma independiente por la duración completa del audio, por lo que el coste aumenta linealmente con el número de canales.
Controla la estructura de la respuesta cuando use_multi_channel está activado. ‘separate’ (predeterminado) devuelve una transcripción por canal en ‘transcripts’. ‘combined’ combina todos los canales en una única transcripción cuyas palabras se ordenan por hora de inicio, cada una con un ‘channel_index’, siguiendo la estructura de respuesta de un solo canal. ‘combined’ requiere marcas de tiempo (timestamps_granularity no puede ser ‘none’) y no admite la detección ni la redacción de entidades.
Detecta entidades en la transcripción. Puede ser ‘all’ para detectar todas las entidades, una cadena de texto con un único tipo o categoría de entidad, o una lista de tipos o categorías de entidades. Las categorías incluyen ‘pii’, ‘phi’, ‘pci’, ‘other’ y ‘offensive_language’. Cuando está activado, las entidades detectadas se devolverán en el campo ‘entities’ con su texto, tipo y posiciones de caracteres. El uso de este parámetro conlleva un recargo adicional del 30 % sobre el coste base de la transcripción.
Indica si se deben detectar los roles de los hablantes (agente frente a cliente). Requiere diarize=true. No se puede usar con use_multi_channel=true. Cuando está activado, los valores de speaker_id serán ‘agent’ y ‘customer’ en lugar de ‘speaker_0’, ‘speaker_1’, etc. Su uso conlleva un recargo adicional del 10 % sobre el coste base de transcripción.
Oculta entidades del texto de la transcripción. Acepta el mismo formato que entity_detection: ‘all’, una categoría (‘pii’, ‘phi’) o tipos de entidad específicos. Debe ser un subconjunto de entity_detection. Cuando la ocultación está activada, no se devolverá el campo entities. El uso de este parámetro conlleva un recargo adicional del 30 % sobre el coste base de la transcripción.
Una lista de términos clave para orientar la transcripción hacia ellos. Los términos clave son palabras o frases que quieres que el modelo reconozca con mayor precisión. El número de términos clave no puede superar los 1000. La longitud de cada término clave debe ser inferior a 50 caracteres. Los términos clave pueden contener como máximo 5 palabras (tras la normalización). Por ejemplo, [“hello”, “world”, “technical term”]. No se admiten los siguientes caracteres: <, >, {, }, [, ], \. El uso de este parámetro conlleva un recargo adicional del 20 % sobre el coste base de la transcripción. Cuando se proporcionan más de 100 términos clave, se aplica una duración mínima facturable de 20 segundos por solicitud.
