AI metadata API

Status: v1.1.0
Laatst bijgewerkt: 28/05/26

1. Inleiding

Met verschillende AI-technieken zoals spraak- en gezichtsherkenning, wordt door meemoo voor geselecteerd audiovisueel materiaal specifieke, verrijkende metadata gegenereerd. Het genereren gebeurt in zogeheten pipelines. Het uitvoeren van een pipeline op een enkel object is een taak (of task), bijvoorbeeld: de transcriptie aanmaken van een audiobestand.

De AI metadata API maakt de gegenereerde metadata beschikbaar voor contentpartners, onder meer:

• taakresultaten van AI-verwerkingen op fragmenten
• matches tussen gedetecteerde personen en de referentieset
• metadata van personen in de referentieset
• transcripties en speech-to-textresultaten
• output van Named Entity Recognition (NER)

De API is bedoeld voor (externe) ontwikkelaars van contentpartners die de AI-gegenereerde metadata in hun systemen willen integreren.

2. Authenticatie & Autorisatie

De API is alleen toegankelijk voor geautoriseerde gebruikers. Autorisatie verloopt via een OAuth2.0 flow met Bearer Token, aan te vragen via de volgende URL: https://oas.hetarchief.be/token.

De authenticatieflow gebruikt client_credentials als grant_type met het e-mailadres en het wachtwoord van je meemoo-account als credentials (Client Credentials - OAuth 2.0 Simplified).

REQUEST

curl -X POST "https://oas.hetarchief.be/token" \
–u "<email>:<password>" \
-d "grant_type=client_credentials" \
-d "expires_in=3600

RESPONSE

{
  "access_token": "<bearer token>",
  "expires_in": 3600,
  "token_type": "bearer"
}

3. API architectuur

Deze API is een GraphQL endpoint waarnaar je een query stuurt waarin je zelf bepaalt voor welke velden je data wil krijgen.

De API biedt een view per metadatatype als resultaat van een pipeline. Elke view bevat op taakniveau het resultaat van de verwerking uitgevoerd op een mediafragment of een match met een referentieset.

De beschikbare views en de metadatabeschrijving zijn:

• face_tasks: detectie van gezichten/personen op videofragmenten
• image_tasks: detectie van gezichten/personen op foto
• face_matches: matches tussen gedetecteerde personen en de referentieset voor video
• image_matches: matches tussen gedetecteerde personen en de referentieset voor foto
• refset_persons: metadata van personen in de referentieset
• speech_tasks: speech-to-text metadata en transcripties
• ner_tasks: NER en textrazor metadata

4. Endpoints

De API wordt aangeboden via: https://services.viaa.be/ai-results/v1/graphql. De endpoint is beveiligd en kan alleen bevraagd worden door een Bearer token mee te geven (zie boven: 2. Authenticatie & Autorisatie). Met typische GraphQL queries kan flexibel alle of een deel van de (meta)data van een of meer taken uit een pipeline opgevraagd worden.

Het is mogelijk het aantal resultaten van de query te beperken met een limit en door een offset mee te geven om bijvoorbeeld de resultaten te pagineren. Je kan de resultaten ook filteren door een where clause mee te geven in de query. De velden waarop gefiltered kan worden kunnen met een standaard introspect query opgevraagd worden of worden ingevuld door een query builder te gebruiken.

Bijvoorbeeld voor face_tasks:

• cluster_uuid
• cp
• match_score
• matched_time
• refset_person_id
• refset_person_name
• refset_person_wiki_id
• time_intervals

Het onderstaande voorbeeld van een typische query vraagt de face_tasks view op via het GraphQL endpoint, waarbij <...> de in de response gewenste datavelden van de view zijn. Zie verder bij hoofdstuk ‘5. Data views’ voor een volledig overzicht van de beschikbare velden per view.

GRAPHQL QUERY

query GetFaceTasks($limit: Int!, $offset: Int!, $status: [String!]) {
 face_tasks(
   limit: $limit
   offset: $offset
   where: { status: { _in: $status } }
 ) {
   <...>
 }
}

cURL REQUEST

echo '{
  "query": "query GetFaceTasks($limit: Int!, $offset: Int!, $status: [String!]) {
    face_tasks(
      limit: $limit
      offset: $offset
      where: { 
        status: {
          _in: $status
        }
      }
    )
    {
      task_id
      processed_time
      status
      cp
      title
    }
  }",
  "variables": {
    "limit": 1,
    "offset": 1,
    "status": "succeeded"
  }
}' | tr -d '\n' | curl --silent \
  -X POST "https://services.viaa.be/ai-results/v1/graphql" \
  -H "Authorization: Bearer <bovenstaand bearer token>" \
  -H "Content-Type: application/json" \
  -d @-

RESPONSE

{
  "data": {
    "face_tasks": [
      {
        "task_id": "<task id>",
        "processed_time": "<processed time>",
        "status": "succeeded",
        "cp": "OR-xxxxxxxx",
        "title": "Example fragment"
      }
    ]
  }
}

5. Data views

• Timestamps worden weergegeven in ISO-8601 waar van toepassing.
• De precieze velden die je opvraagt, bepaal je zelf in je GraphQL-query.
• Ruwe outputvelden zoals processed_json, textrazor_json, transcript_json en audio_classification_json zijn bedoeld voor integraties die de volledige service-output willen verwerken.

5.1 face_matches | image_matches

Geeft matches terug tussen gedetecteerde personen en personen in de referentieset.

Velden

5.2 face_tasks | image_tasks

Geeft resultaten terug van gezichts- en persoonsdetectie op fragmenten.

5.3 ner_tasks

Geeft NER-resultaten en gerelateerde ruwe output terug.

5.4 speech_tasks

Geeft speech-to-textresultaten, transcripties en aanverwante metadata terug.

5.5 refset_persons

Geeft metadata terug over personen in de referentieset.

6. Voorbeelden van gebruik

Het gebruik van de API wordt toegelicht met 2 concrete voorbeelden in: give-graphql-query-examples.

Deze repository bevat twee use cases die de AI metadata API gebruiken:

• alle beschikbare metadata ophalen
• ruwe data downloaden

Zie ook de README.md in de repository voor uitleg.

6.1 Voorbereiding

• Zorg dat Python 3.11+ geïnstalleerd is op je systeem: Python installatie
• git clone de repository
• Kopieer het .env-template en hernoem het naar .env
• Vul in het .env bestand de USER_EMAIL en PASSWORD velden in met de waarden van een account gelinkt aan jouw organisatie
• Voer de volgende commando’s uit in een terminal om de virtuele omgeving te activeren zodat de scripts kunnen gerund worden:

Linux/MacOS:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip wheel
python -m pip install -r requirements.txt

Windows:

py -3.11 -m venv .venv
.venv\Scripts\activate
python -m pip install -U pip wheel
python -m pip install -r requirements.txt

6.2 De scripts uitvoeren

Metadata downloaden

Gebruik download_meemoo_ai_data.py om alle beschikbare metadata voor je organisatie op te halen en lokaal als JSON op te slaan.

Het script maakt in output/ een submap per view aan:

• face_tasks
• face_image_tasks
• face_matches
• face_image_matches
• refset_persons
• speech_tasks
• ner_tasks

In elke submap wordt de data gepagineerd opgeslagen. Elk JSON-bestand bevat dus 1 pagina met resultaten.

Het script verwacht dat de uitvoermap nog niet bestaat. Wil je de export opnieuw uitvoeren, verwijder dan eerst de map output/.

# vergeet niet eerst je virtuele omgeving te activeren
python download_meemoo_ai_data.py

Ruwe AI output downloaden

Gebruik daarna download_meemoo_raw_ai_files.py om per taak de ruwe bestanden op te halen.

Voer dit script pas uit nadat download_meemoo_ai_data.py succesvol heeft gedraaid. Het script gebruikt namelijk de eerder geëxporteerde metadata in output/ om te bepalen welke taken moeten worden opgehaald.

In de huidige versie van het script worden ruwe bestanden voor speech_tasks gedownload naar output/speech_tasks/tasks/<task_id>/. Per taak kunnen daar onder meer volgende bestanden in terechtkomen:

• metadata.json: metadata van de taak
• speechmatics_raw.json: ruwe JSON-respons van Speechmatics
• subtitles.srt: transcriptie in SRT-formaat
• subtitles.vtt: transcriptie in VTT-formaat
• transcription.txt: platte tekstversie van de transcriptie
• audio_classification.json: output van de audio-classificatie

De map output/speech_tasks/tasks/ mag nog niet bestaan wanneer je het script start. Wil je de ruwe bestanden opnieuw downloaden, verwijder die map dan eerst.

Afhankelijk van het aantal taken kan dit script enige tijd duren. Tijdens het uitvoeren toont het script een voortgangsbalk.

# vergeet niet eerst je virtuele omgeving te activeren
python download_meemoo_raw_ai_files.py