> ## Documentation Index
> Fetch the complete documentation index at: https://docs.identifai.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Clasifica un audio de voz desde una URL

> Envía un audio de voz para su clasificación

🔁 El formato de la respuesta depende del header `Accept`:

`Accept: application/json` → `{ "identifier": "..." }`

 Otros valores (p. ej., `text/plain`) → texto plano con solo la cadena del identificador. Consulta [Clasifica un audio de voz](/es/api-reference/classification/submit-a-speech-for-classification) para ver la lista de tipos MIME admitidos y los límites de tamaño.



## OpenAPI

````yaml es/api-reference/api-swagger-dev-documentation.json POST /api/audio_fromurl
openapi: 3.0.0
info:
  title: API de identifAI
  version: 1.0.0
  description: >-
    API para integrar las funcionalidades de clasificación de imágenes y vídeos
    de identifAI.<br><details><summary>**Cómo obtener tu API key**</summary>Para
    obtener tu API key, sigue estos sencillos pasos:   <ol><li><p>**Crea un
    perfil de usuario y accede a la plataforma**</p>Si todavía no tienes una
    cuenta, visita nuestra plataforma y crea un perfil de usuario. Después de
    completar el registro y verificar tu correo electrónico, accede con tus
    credenciales.</li><li><p>**Abre el menú de usuario**</p>Después de acceder,
    haz clic en tu nombre o en el icono de usuario en la esquina superior
    derecha de la pantalla.</li><li><p>**Selecciona la opción API key**</p>En el
    menú desplegable que aparece, selecciona la opción "Api-Key". Desde allí
    puedes ver o generar tu API key.</li></ol>¡Ya puedes usar tu API key con
    nuestra API!</details><details><summary>**Cómo usar la API**</summary>Para
    usar la API, realiza primero una solicitud **POST** para iniciar la
    clasificación. Después usa el ***identificador*** devuelto por la solicitud
    **POST** para obtener los resultados.

    <details>

    <summary>**1. Clasificación de imágenes**</summary>
      * Para clasificar una imagen, realiza una solicitud **POST** a `/api/classification` con los parámetros obligatorios (para más detalles sobre los parámetros, consulta la sección *"Clasificación"* más abajo).
      * En la respuesta recibirás el ***identificador*** de la imagen clasificada.
      * Usa el ***identificador*** recibido para obtener los resultados de la clasificación con una solicitud **GET** a `/api/classification/{identifier}` (para más detalles sobre cómo estructurar la solicitud, consulta la sección *"Clasificación"* más abajo).
      * La respuesta contiene los resultados de la clasificación de la imagen en formato JSON.<br>En la respuesta encontrarás un array ***results***, con los resultados de la clasificación de cada modelo usado, y un array ***verdicts***, con los resultados de cada heurística aplicada.<br>Si la clasificación aún no se ha completado, sigue enviando la solicitud **GET** hasta que el resultado esté disponible.</details><details><summary>**2. Clasificación de vídeos**</summary>
        * Para clasificar un vídeo, realiza una solicitud **POST** a `/api/classification_video` con los parámetros obligatorios (para más detalles sobre los parámetros, consulta la sección *"Clasificación"* más abajo).
        * En la respuesta recibirás el ***identificador*** del vídeo clasificado.
        * Usa el ***identificador*** recibido para obtener los resultados de la clasificación con una solicitud **GET** a `/api/classification_video/{identifier}` (para más detalles sobre cómo estructurar la solicitud, consulta la sección *"Clasificación"* más abajo).
        * La respuesta contiene los resultados de la clasificación del vídeo en formato JSON. Para la clasificación, el vídeo se divide en *frames*.<br> En la respuesta encontrarás un array ***results***, con el resultado de la clasificación de cada modelo aplicado a cada frame analizado, y un array ***verdicts***, con los resultados de cada heurística usada.<br> Si la clasificación no se ha completado, sigue enviando la solicitud **GET** hasta que se devuelvan los resultados finales.</details><details><summary>**3. Todas las clasificaciones**</summary>El endpoint `/api/classifications` devuelve todas las clasificaciones de imágenes realizadas por un usuario, con los resultados de todas las solicitudes de clasificación de imágenes anteriores.</details><details><summary>**4. Gestión de usuarios**</summary>  El endpoint **POST** `/api/user` permite crear un usuario, mientras que el endpoint **DELETE** `/api/user` sirve para eliminar un usuario (para la estructura de las solicitudes, consulta la sección de usuarios más abajo).</details></details>
servers:
  - url: https://backend.identifai.net
security: []
tags:
  - name: Classification
    description: Rutas de clasificación
  - name: Infrastructure
    description: Rutas de infraestructura
  - name: User
    description: Acciones del usuario
  - name: Partner
    description: Acciones de los partners
paths:
  /api/audio_fromurl:
    post:
      tags:
        - Classification
      summary: Clasifica un audio de voz desde una URL
      description: |-
        Envía un audio de voz para su clasificación

        🔁 El formato de la respuesta depende del header `Accept`:

        `Accept: application/json` → `{ "identifier": "..." }`

         Otros valores (p. ej., `text/plain`) → texto plano con solo la cadena del identificador. Consulta [Clasifica un audio de voz](/es/api-reference/classification/submit-a-speech-for-classification) para ver la lista de tipos MIME admitidos y los límites de tamaño.
      parameters:
        - name: Accept
          in: header
          description: >-
            Tipo de contenido de la respuesta. Valores admitidos:
            application/json, text/plain.
          required: false
          schema:
            type: string
            enum:
              - application/json
              - text/plain
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file_url:
                  type: string
                  description: La URL del audio de voz que se va a clasificar.
                ref_id:
                  type: string
                  description: >-
                    ID de referencia opcional que se asocia a la solicitud de
                    clasificación.
                webhook_url:
                  type: string
                  description: >-
                    Si se indica, el resultado de la clasificación también se
                    envía automáticamente a la URL introducida. Si no, el
                    resultado se obtiene mediante polling del [endpoint
                    correspondiente](./get-classification-result-speech). Ten en
                    cuenta que para usar una URL de callback del webhook **debes
                    solicitar una habilitación específica**; si no, el parámetro
                    se ignora. Además, el sistema puede guardar en caché los
                    resultados de los análisis de envíos repetidos, es decir,
                    envíos del mismo archivo con las mismas opciones: en este
                    caso no se llama al webhook y los resultados solo están
                    accesibles mediante polling del [endpoint
                    correspondiente](./get-classification-result-speech).
                deferred_webhook_url:
                  type: string
                  description: >-
                    Si se indica, la URL se notifica una sola vez cuando los
                    **resultados diferidos** del envío están completos (p. ej.,
                    las explicaciones textuales de los mapas XAI y de la
                    heatmap), después de los resultados principales enviados a
                    `webhook_url`. La notificación lleva el evento
                    `submission.deferred.completed`: consulta [Resultados
                    diferidos](/es/api-reference/deferred-results) para ver el
                    payload. Se aplican la misma habilitación, las mismas
                    restricciones de dominio y la misma autenticación que en
                    `webhook_url`. La entrega es *at least once*: deduplica por
                    `identifier`, y ten en cuenta que una notificación `expired`
                    puede ir seguida de una segunda con el resultado real, que
                    la sustituye. Si se omite o está vacía, no se envía ninguna
                    notificación de resultados diferidos.
                no_cache:
                  type: boolean
                  description: >-
                    Establécelo en true para obligar al sistema a volver a
                    procesar la imagen aunque ya se haya enviado con las mismas
                    opciones. Esto puede suponer costes adicionales.
                audio_timestamps:
                  type: string
                  example: 00:00:05.000,00:01:12.500
                  description: >-
                    **[Funcionalidad del plan]** Momentos específicos del audio
                    de voz que se van a analizar. Lista de timecodes separados
                    por comas en formato `HH:MM:SS.mmm`, medidos desde el inicio
                    del archivo (p. ej., `00:00:05.000,00:01:12.500`). Cuando se
                    indica, en lugar de dividir el audio en segmentos a lo largo
                    de toda su duración, el sistema analiza un breve segmento de
                    audio centrado en cada momento indicado; los momentos lo
                    bastante cercanos como para caer en el mismo segmento se
                    analizan juntos en un único segmento. Los momentos
                    duplicados se cuentan una sola vez. Puedes indicar hasta
                    **30** momentos si tu plan de precios te permite elegir el
                    número de segmentos de audio; si no, hasta **5**. **Se cobra
                    un segmento de audio por cada momento distinto**: los
                    segmentos que no se generan (momentos agrupados, momentos
                    posteriores al final del audio) se reembolsan al terminar el
                    análisis. Si ningún momento cae dentro del audio, la
                    clasificación termina con un error. **Para usar esta opción
                    debe estar habilitada en tu plan de precios**; si no, el
                    parámetro se ignora.
              required:
                - file_url
      responses:
        '200':
          description: >-
            El identificador de la clasificación. El formato depende del header
            Accept.
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                    example: >-
                      8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0
              example:
                identifier: >-
                  8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0
            text/plain:
              schema:
                type: string
                example: >-
                  8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0
              example: 8d64370a87b820cc1cf620338f5c898bab37439c9a405f32d9eaffc50c4f27b0
        '400':
          description: >-
            El usuario no tiene créditos suficientes para realizar la operación,
            la solicitud contiene parámetros incorrectos o el medio no ha
            superado los controles de validación.
          content:
            application/json:
              examples:
                invalid_timestamps:
                  summary: Timestamps no válidos
                  value:
                    error:
                      audio_timestamps:
                        - >-
                          The audio timestamps must be a comma-separated list of
                          timecodes in HH:MM:SS.mmm format.
                missing_file_url:
                  summary: Ejemplo de error de validación
                  value:
                    file_url: The file_url field is required.
                invalid_url:
                  summary: URL no válida
                  value:
                    error: The provided file_url is not a valid URL.
                unsupported_format:
                  summary: Formato de archivo no compatible
                  value:
                    error: The file format at the provided URL is not supported.
                file_too_large:
                  summary: Archivo demasiado grande
                  value:
                    error: >-
                      The file at the provided URL exceeds the maximum allowed
                      size of 50MB.
        '401':
          description: API key desconocida o ausente.
          content:
            application/json:
              example:
                error: Unauthorized
        '403':
          description: >-
            El usuario no está autorizado a acceder a esta API o no ha aceptado
            los Términos del servicio.
          content:
            application/json:
              example:
                error: Forbidden
        '429':
          description: Demasiadas solicitudes.
          content:
            application/json:
              example:
                error: Too Many Attempts.
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-Api-Key
      in: header
      description: Tu API key.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.