Méthodes complémentaires de l'API REST

Méthodes complémentaires de l'API REST

L'API REST de YobiYoba peut aussi être utilisée pour interagir avec votre compte. Consulter le temps restant, vos fichiers, vos dossiers, etc...
Les méthodes complémentaires s'utilisent via l'URL suivante :

• Exemple de cURL

Comme pour les méthodes de base, la clé d'API doit être ajouté en tant qu'en-tête HTTP "api-key".
Le retour des methodes complémentaires est toujours au format JSON. Les retours contiennent des structures définient qui se basent sur les définition des Entités.

Paramètres autorisés en query-string :

• fields : Ce paramètre est utilisé pour selectionner les champs à retourner par l'API REST.
  S'il n'est pas indiqué, les champs par default des entités seront retournés.
  La veleur de fields doit être un enchainement de valeur séparé par une virgule (U+002C COMMA, “,”).
  Si vous demandez un ensemble de champs pour un type d'entité donné, la réponse ne comprendra pas les champs par défaut.
  Si un champ d'une entité est lui-même une entité, le paramètre fields peut également être utilisé pour sélectionner les champs à renvoyer (sub_entity_field_name.field_name).
  Le jocker * peut être utilisé pour retourner l'ensemble des champs.
  
• page : Les points de terminaison qui permettent de récuperer l'intégralité d'un type d'Entités retourne le contenu de façon paginée. Le numéro de la page doit donc être passé en paramètre. Si ce paramètre n'est pas fourni, la valeur par defaut interprétée est 1.
  
• size : La taille des retours paginés peut être modifié via ce paramètre. Ce paramètre à une valeur par defaut et une valeur maximale pour chacune des méthodes compatibles.
  
• log : Permet de journaliser un appel à l'API. La valeur attendue est true (log=true). Retrouvez les appels journalisés sur la page "Journal des appels".
  

• Exemple d'utilisation des paramètres en query-string

Entités

Notre API REST donne accès à différentes Entités vous permettant ainsi de gerer vos fichiers et votre compte.

• Pagination : Un objet Pagination est ajouté dans tous les retours, des points de terminaisons de l'API, qui supportent la fonctionnalité de pagination.
• APIKey : Contient les informations relatives à votre clé API, comme la date de création ou le nom de la clé.
• ExportOption : Un objet ExportOption permet de définir les paramètres lorsque l'on veut exporter une transcription.
• File : Représente un fichier audio qui existe ou a existé sur votre compte. Un File est créé lorsque vous envoyez un fichier à partir de l'interface web ou lorsque vous importez un traitement à partir de l'API.
• Folder : Représente un répertoire créé par l'utilisateur pour organiser des File.
• Language : Un objet Language contenant des informations sur une langue.
• Result : Correspond au résultat du traitement disponible à partir de l'interface web. Un Result est créé lorsque l'utilisateur exécute un traitement à partir de l'interface web ou lorsqu'un Treatment est importé à partir de l'API.
• Revision : Il s'agit d'une révision textuelle d'un Result, créée à partir de l'éditeur.
• Summary : Contient les informations d'un résumé effectué à partir d'un Result ( et d'une Revision).
• SummaryOption : Objet contenant les options utilisées pour générer un résumé de transcription
• TimeCounter : This is the user's time counter. It indicates the time available for processing.
• TimeRestriction : Correspond à une restriction de temps appliquée au compte par son compte principal.
• TranslationPair : Un objet TranslationPair permet de definir un couple de langue utilisé pour la traduction.
• Treatment : Représente un processus exécuté à partir d'un appel API. Seuls les appels aux méthodes de bases de l'API (bs_* et cts_*) entraînent la création d'un Treatment.

exemple d'Entité Pagination #1{
    "current": "<url_current>",
    "last": "<url_last_page>",
    "next": "<url_next_page>"
}                                            

exemple d'Entité Pagination #2{
    "current": "<url_current>",
    "last": "<url_last_page>",
    "previous": "<url_previous_page>"
}                                            

exemple d'Entité Pagination #3{
    "current": "<url_current>",
    "last": "<url_last_page>",
    "previous": "<url_previous_page>",
    "next": "<url_next_page>"
}                                            

exemple d'Entité APIKey{
    "id": "YG",
    "name": "Documentation team's key",
    "creation_date": "2026-06-18T21:02:19+00:00",
    "deactivation_date": null,
    "expiration_date": "2027-12-18T09:02:19+00:00",
    "key": "rNFg7Gu***************",
    "state": 0
}                                            

exemple d'Entité ExportOption #1{
    "format": "pdf"
}                                            

exemple d'Entité ExportOption #2{
    "format": "pdf",
    "options": [
        "include_speakername",
        "include_timecode"
    ]
}                                            

exemple d'Entité ExportOption #3{
    "format": "pdf",
    "options": [
        "include_speakername",
        "include_timecode",
        "merge_transcription",
        "add_title"
    ],
    "title": "Export Title"
}                                            

exemple d'Entité ExportOption #4{
    "format": "pdf",
    "options": [
        "translation"
    ],
    "translation_pairs": [
        {
            "from": {
                "code": "eng"
            },
            "to": {
                "code": "fre"
            }
        }
    ]
}                                            

exemple d'Entité File{
    "id": "VO",
    "originalname": "My_File_1.mp3",
    "displayablename": "",
    "name": "0e2f5fb315d0-0000007f-0000007f-6e5e-d6c65ac081d4d7fdf252e4624b55de96",
    "creationdate": "2026-06-18T21:02:19+00:00",
    "duration": 2340,
    "bytes": 10240,
    "process_state": 3,
    "deleted": true,
    "folder": {
        "id": "PQ",
        "name": "My directory 1"
    },
    "results": []
}                                            

exemple d'Entité Folder #1{
    "id": "PQ",
    "parentId": null,
    "name": "My directory 1",
    "children": [
        {
            "id": "81",
            "name": "My sub-directory of My directory 1"
        }
    ],
    "files": [
        {
            "id": "7YrV",
            "originalname": "Interview 5 - Membre du collectif 3.MP3",
            "name": "0eb32ca6dc5e-00000025-00000059-21f1-0fb103bcc7e1311871181f371a4d30d2"
        },
        {
            "id": "4pk",
            "originalname": "Interview 4 - YP.MP3",
            "name": "0e7fa3020e60-00000025-000000b9-1c40-a30c7d41c203590a24e0c26a4bb1080c"
        },
        {
            "id": "kkV",
            "originalname": "Interview 3 - Maire.MP3",
            "name": "0e78fe03f375-00000025-00000059-3cdd-b20aa537dcead286176b2fe27b4419d6"
        }
    ]
}                                            

exemple d'Entité Folder #2{
    "id": "81",
    "parentId": "PQ",
    "name": "My sub-directory of My directory 1",
    "children": [],
    "files": [
        {
            "id": "wJM5",
            "originalname": "Entretien 4 - ALD.MP3",
            "name": "0eb58f4afda1-00000025-00000059-7ea8-c9d50353afcf93f4440b90baba4e260b"
        },
        {
            "id": "Kw1o",
            "originalname": "Entretien 1 - VR.MP3",
            "name": "0eb32ed751a7-00000025-00000059-243f-a35a0b22392e808b9c41ea7b5778b0c7"
        },
        {
            "id": "Lem1",
            "originalname": "Entretien 2 - B.MP3",
            "name": "0eb32ea5ae90-00000025-00000059-2501-3d85ee94f49af165d1019da633440570"
        },
        {
            "id": "j9PP",
            "originalname": "Entretien 3 - AL.MP3",
            "name": "0eb414a2587f-00000025-00000059-7193-0a7d9cfa0bb67068acc4f293a45f920a"
        }
    ]
}                                            

exemple d'Entité Language #1{
    "code": "eng",
    "label": "English"
}                                            

exemple d'Entité Language #2{
    "code": "fre",
    "label": "French"
}                                            

exemple d'Entité Result{
    "id": "mv",
    "datestart": "2026-06-18T21:01:59+00:00",
    "dateend": "2026-06-18T21:02:19+00:00",
    "deleted": true,
    "process_state": 2,
    "spokenduration": 157,
    "signalduration": 234,
    "file": {
        "id": "VO",
        "originalname": "My_File_1.mp3",
        "name": "0e2f5fb315d0-0000007f-0000007f-6e5e-d6c65ac081d4d7fdf252e4624b55de96"
    },
    "treatment": {
        "id": "Xn",
        "filename": "My_File_1.mp3",
        "in_process": true
    },
    "revisions": null,
    "summaries": null
}                                            

exemple d'Entité Revision{
    "id": "dBi8",
    "number": 2,
    "dateupdate": "2026-06-18T21:02:19+00:00"
}                                            

exemple d'Entité Summary{
    "id": "KG6",
    "creation_date": "2025-01-23T17:30:00+00:00",
    "title": "Conversation between two people.",
    "text": "Alice and Mark discussed their weekend plans. Alice suggested going hiking, while Mark preferred a movie night because the weather forecast predicted rain. They agreed to check the weather on Saturday morning and decide then.",
    "language": "eng",
    "process_state": 2,
    "progression": 1,
    "deleted": false,
    "result": {
        "id": "mv"
    }
}                                            

exemple d'Entité SummaryOption{
    "include_speakers": true
}                                            

exemple d'Entité TimeCounter{
    "id": "Op",
    "remaining_second": 12.6
}                                            

exemple d'Entité TimeRestriction{
    "minutes_used": 25,
    "minutes_limit": 600,
    "period_start": "2026-06-18T00:00:00+00:00",
    "period_end": "2026-07-18T00:00:00+00:00",
    "period_type": "monthly"
}                                            

exemple d'Entité TranslationPair{
    "from": {
        "code": "eng",
        "label": "English"
    },
    "to": {
        "code": "fre",
        "label": "French"
    }
}                                            

exemple d'Entité Treatment{
    "id": "Xn",
    "filename": "My_File_1.mp3",
    "sessionId": "60182c65-7f000101-567a",
    "datestart": "2026-06-18T21:01:59+00:00",
    "dateend": "2026-06-18T21:02:19+00:00",
    "language": "eng",
    "type": "brodcast",
    "in_process": true,
    "error_message": null,
    "results": [],
    "apikey": {
        "id": "YG",
        "name": "Documentation team's key",
        "key": "rNFg7Gu***************"
    }
}                                            

Points de terminaisons disponibles

Clé d'API

• GET/api/v1/apikeys : Retourne la liste de vos APIKey.
• GET/api/v1/apikeys/{apikey_id[,another_apikey_id,...]} : Retourne une ou plusieurs APIKey selon les paramètres fournis.
• PUT/api/v1/apikey : Met à jour les données d'une APIKey.




Langue de traduction

• GET/api/v1/translation/pairs : Renvoie la liste des paires de langues disponibles pour la traduction.




Fichiers

• GET/api/v1/files : Retourne la liste de vos File.
• GET/api/v1/files/{file_id[,another_file_id,...]} : Retourne un ou plusieurs File selon les paramètres fournis.
• PUT/api/v1/file : Met à jour les données d'un File.
• DELETE/api/v1/file/{file_id} : Supprime définitivement un File de votre compte.
• GET/api/v1/export/files : Exporte toutes les Revision de tous les Result d'un ou plusieurs File dans le format choisi. Si l'export concerne plusieurs Revision, une archive sera générée.




Dossiers

• GET/api/v1/folders : Retourne la liste des vos Folder.
• GET/api/v1/folders/{folder_id[,another_folder_id,...]} : Retourne un ou plusieurs Folder selon les paramètres fournis.
• PUT/api/v1/folder : Met à jour les données d'un Folder.
• POST/api/v1/folder : Créer un Folder
• DELETE/api/v1/folder/{folder_id} : Supprime un Folder de façon permanente.




Temps disponible

• GET/api/v1/timecounter : Retourne votre compteur de temps.
• GET/api/v1/account/timerestrictions/ : Retourne la liste des TimeRestriction appliquées à votre compte.




Traitement via les méthodes de base

• GET/api/v1/treatments : Retourne la liste de vos Treatment.
• GET/api/v1/treatments/{treatment_id[,another_treatment_id,...]} : Retourne un ou plusieurs Treatment selon les paramètres fournis.
• GET/api/v1/archive/treatments : Retourne la liste de vos Treatment qui ont été archivés dans notre système.
• GET/api/v1/archive/treatments/{treatment_id[,another_treatment_id,...]} : Retourne un ou plusieurs Treatment ,qui ont été archivés, selon les paramètres fournis.
• POST/api/v1/treatments/import : Importe un ou plusieurs Treatment dans vos File/Result.
• GET/api/v1/export/treatments : Exporte un ou plusieurs Treatment dans le format choisi.




Résultats de traitement

• GET/api/v1/results : Retourne la liste de vos Result.
• GET/api/v1/results/{result_id[,another_result_id,...]} : Retourne un ou plusieurs Result selon les paramètres fournis.
• GET/api/v1/export/results : Exporte toutes les Revision d'un ou plusieurs Result dans le format choisi.
• DELETE/api/v1/result/{result_id} : Supprime définitivement un Result de votre compte.




Révisions de transcription

• GET/api/v1/export/revisions : Exporte une ou plusieurs Revision dans le format choisi.




Résumé de transcription

• GET/api/v1/summaries : Retourne la liste de vos Summary.
• GET/api/v1/summaries/{summary_id[,another_summary_id,...]} : Retourne une ou plusieurs Summary selon les paramètres fournis.
• POST/api/v1/summary : Demander la génération d'un Summary.

Clé d'API

Gestion des clés d'API

GET /api/v1/apikeys

GET /api/v1/apikeys/{apikey_id[,another_apikey_id,...]}

PUT /api/v1/apikey

Langue de traduction

Accès aux informations permettant d'effectuer des traductions

GET /api/v1/translation/pairs

Fichiers

Gestion de vos fichiers

GET /api/v1/files

GET /api/v1/files/{file_id[,another_file_id,...]}

PUT /api/v1/file

DELETE /api/v1/file/{file_id}

GET /api/v1/export/files

Dossiers

Gestion de vos dossiers

GET /api/v1/folders

GET /api/v1/folders/{folder_id[,another_folder_id,...]}

PUT /api/v1/folder

POST /api/v1/folder

DELETE /api/v1/folder/{folder_id}

Temps disponible

Accès aux informations concernant votre temps disponible ou les restrictions sur son utilisation.

GET /api/v1/timecounter

GET /api/v1/account/timerestrictions/

Traitement via les méthodes de base

Permet d'interagir avec vos traitements effectués via les méthodes de base.

GET /api/v1/treatments

GET /api/v1/treatments/{treatment_id[,another_treatment_id,...]}

GET /api/v1/archive/treatments

GET /api/v1/archive/treatments/{treatment_id[,another_treatment_id,...]}

POST /api/v1/treatments/import

GET /api/v1/export/treatments

Résultats de traitement

Permet d'interagir avec vos résultats de traitement, lancés via l'interface graphique ou importés depuis un traitement.

GET /api/v1/results

GET /api/v1/results/{result_id[,another_result_id,...]}

GET /api/v1/export/results

DELETE /api/v1/result/{result_id}

Révisions de transcription

Permet d'interagir avec les différentes révisions créées lors de l'édition d'une transcription (Résultat) dans l'éditeur.

GET /api/v1/export/revisions

Résumé de transcription

Gestion des résumés de vos transcriptions.

GET /api/v1/summaries

GET /api/v1/summaries/{summary_id[,another_summary_id,...]}

POST /api/v1/summary