APIs
========

Générer une transcription
--------------------------

.. raw:: html

   <script>
   document.addEventListener("DOMContentLoaded", function() {
     var h2s = document.querySelectorAll("h2");
     h2s.forEach(function(h) {
       if (h.textContent.trim().startsWith("Générer une transcription")) {
         var badge = document.createElement("span");
         badge.className = "api-version-badge";
         badge.textContent = "v1.0";
         h.appendChild(badge);
       }
     });
   });
   </script>

Pour transcrire un enregistrement audio, envoyez votre fichier via l'endpoint ``get-upload-url``.
Celui-ci génère une URL présignée vous permettant de téléverser votre fichier directement vers
notre stockage sécurisé. Une fois le téléversement complété, la transcription est lancée
automatiquement et le résultat est transmis à votre webhook.


- `Étape 1 — Obtenir une URL présignée <#etape-1>`_
- `Étape 2 — Téléverser le fichier <#etape-2>`_
- `Étape 3 — Recevoir la transcription <#etape-3>`_
- `Exemple de code <#exemple-de-code>`_

.. raw:: html

   <div class="step-card" id="etape-1">
   <div class="step-header"><span class="step-number">1</span> Obtenir une URL présignée</div>

:http:`POST https://api2.app.plumeia.ca/get-upload-url`

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Paramètre
     - Type
     - Description
   * - ``Content-Type`` *(header)*
     - string
     - Doit être ``application/json``
   * - ``x-api-key`` *(header)*
     - string
     - Clé API fournie par Plume
   * - ``filename``
     - string
     - Nom du fichier à téléverser
   * - ``username``
     - string
     - Identifiant de l'utilisateur
   * - ``language``
     - string
     - Langue de l'enregistrement (``fr`` ou ``en``)
   * - ``webhook`` *(optionnel)*
     - string
     - URL de rappel appelée lorsque la transcription est disponible. Si absente, le webhook par défaut configuré lors de l'intégration est utilisé.

**Exemple**

.. code-block:: python

    response = requests.post(
        'https://api2.app.plumeia.ca/get-upload-url',
        headers={
            'Content-Type': 'application/json',
            'x-api-key': API_KEY
        },
        json={
            'filename': file_path,
            'username': username,
            'language': language,
            'webhook': 'https://votre-serveur.com/webhook'
        }
    )

**Réponse**

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Champ
     - Type
     - Description
   * - ``upload_url``
     - string
     - URL présignée pour le téléversement
   * - ``headers``
     - object
     - En-têtes à inclure lors du téléversement

.. raw:: html

   </div>

.. raw:: html

   <div class="step-card" id="etape-2">
   <div class="step-header"><span class="step-number">2</span> Téléverser le fichier</div>

Utilisez l'URL et les en-têtes retournés à l'étape précédente pour téléverser votre fichier.
La transcription sera automatiquement lancée et le résultat sera transmis à votre webhook.

:http:`PUT {upload_url}`

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Paramètre
     - Type
     - Description
   * - ``headers``
     - object
     - En-têtes retournés par ``get-upload-url``
   * - ``data``
     - binary
     - Contenu binaire du fichier audio

**Exemple**

.. code-block:: python

    with open(file, 'rb') as f:
        upload_response = requests.put(
            data['upload_url'],
            data=f,
            headers=data['headers']
        )

.. raw:: html

   </div>

.. raw:: html

   <div class="step-card" id="etape-3">
   <div class="step-header"><span class="step-number">3</span> Recevoir la transcription</div>

Une fois le téléversement complété, la transcription est lancée automatiquement. Le résultat
est transmis à votre webhook sous forme d'objet JSON.

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Champ
     - Type
     - Description
   * - ``user_id``
     - string
     - Identifiant de l'utilisateur
   * - ``status``
     - string
     - Statut de la transcription (``SUCCESS`` ou ``ERREUR``)
   * - ``timestamp``
     - string
     - Horodatage marquant la fin de la transcription
   * - ``transcription``
     - string
     - Texte transcrit, ou message d'erreur si la transcription a échoué

**Réponse — succès**

.. code-block:: json

    {
        "user_id": "user01",
        "status": "SUCCESS",
        "timestamp": "timestamp",
        "transcription": "Voici le contenu de l'enregistrement."
    }

**Réponse — erreur**

.. code-block:: json

    {
        "user_id": "user01",
        "status": "ERREUR",
        "timestamp": "timestamp",
        "transcription": "ERREUR: [description de l'erreur]"
    }

.. raw:: html

   </div>

Exemple de code
~~~~~~~~~~~~~~~~

.. raw:: html

   <div class="step-card" id="exemple-de-code">

.. code-block:: python

    import requests

    API_KEY = 'votre_clé_api'

    def upload_file(file_path, username, language, webhook=None):
        response = requests.post(
            'https://api2.app.plumeia.ca/get-upload-url'
            headers={
                'Content-Type': 'application/json',
                'x-api-key': API_KEY
            },
            json={
                'filename': file_path,
                'username': username,
                'language': language,
                'webhook': webhook
            }
        )

        if response.status_code != 200:
            raise Exception(f"Erreur : {response.status_code} : {response.text}")

        data = response.json()

        with open(file_path, 'rb') as f:
            upload_response = requests.put(
                data['upload_url'],
                data=f,
                headers=data['headers']
            )

        if upload_response.status_code != 200:
            raise Exception(f"{upload_response.status_code} : {upload_response.text}")
        else:
            print("Upload successful")

    if __name__ == "__main__":
        try:
            upload_file("docs/myfile.wav", "user01", "fr", "mywebhook.com")
        except Exception as e:
            print(f"Erreur : {e}")

.. raw:: html

   </div>