Référence API

API Reference

Base URL : https://lyricsfree.app/api/v1

Note : Cette page documente les endpoints de façon lisible. Pour envoyer de vraies requêtes interactives depuis le navigateur, utilisez l'interface Swagger — elle permet de tester chaque endpoint avec votre clé API directement.

Authentification

Toutes les requêtes doivent inclure votre clé API via l'en-tête Authorization ou le paramètre api_key.

En-tête HTTP (recommandé)

Authorization: Bearer lf_votre_cle_api

Paramètre de requête

GET /api/v1/songs?api_key=lf_votre_cle_api

Rate limiting

Chaque clé est limitée à 100 requêtes par heure (fenêtre glissante). En cas de dépassement, l'API retourne HTTP 429 avec un en-tête Retry-After indiquant le nombre de secondes avant le reset.

Code	Signification
401	Clé API manquante ou invalide
403	Clé API désactivée
429	Limite de requêtes dépassée
404	Ressource introuvable

Songs

GET/api/v1/songsListe des chansons publiées

Retourne une liste paginée des chansons ayant le statut published, avec artiste principal et featurings. Les paroles ne sont pas incluses.

Query params

langstring

Filtrer par langue principale (ex. fon, fr)

countrystring

Filtrer par nom de pays (ex. Bénin, Sénégal). Voir la liste des pays ci-dessous.

genrestring

Filtrer par genre musical — valeur slug (ex. afrobeats, coupe-decale). Voir la liste des genres ci-dessous.

pageinteger

Numéro de page (défaut : 1)

limitinteger

Résultats par page — max 50 (défaut : 20)

cURL

curl "https://lyricsfree.app/api/v1/songs?lang=fon&limit=5" \
  -H "Authorization: Bearer lf_votre_cle_api"

200 — Réponse

JSON-LD

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "numberOfItems": 42,
  "lf:page": 1,
  "lf:totalPages": 9,
  "lf:limit": 5,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "MusicRecording",
        "@id": "https://lyricsfree.app/songs/1",
        "identifier": 1,
        "name": "Gbe lɔ",
        "inLanguage": "fon",
        "countryOfOrigin": "Bénin",
        "byArtist": {
          "@type": "MusicGroup",
          "identifier": 3,
          "name": "Zeynab"
        }
      }
    }
  ]
}

GET/api/v1/songs/:idDétail d'une chanson avec paroles

Retourne une chanson publiée avec toutes ses lignes de paroles et uniquement les traductions validées. Idéal pour construire des corpus d'entraînement NLP.

Paramètres

idintegerrequis

Identifiant de la chanson

cURL

curl "https://lyricsfree.app/api/v1/songs/1" \
  -H "Authorization: Bearer lf_votre_cle_api"

200 — Réponse

JSON-LD

{
  "@context": "https://schema.org",
  "@type": "MusicRecording",
  "@id": "https://lyricsfree.app/songs/1",
  "name": "Gbe lɔ",
  "inLanguage": "fon",
  "byArtist": { "name": "Zeynab" },
  "lf:lines": [
    {
      "@type": "lf:LyricLine",
      "lf:order": 1,
      "lf:text": "Gbe lɔ mɛ nu",
      "inLanguage": "fon",
      "lf:translations": [
        {
          "@type": "lf:Translation",
          "lf:text": "Le cœur de la forêt",
          "inLanguage": "fr"
        }
      ]
    }
  ]
}

Artists

GET/api/v1/artistsListe des artistes

Retourne une liste paginée de tous les artistes présents dans la base, triés par nom alphabétique.

Query params

pageinteger

Numéro de page (défaut : 1)

limitinteger

Résultats par page — max 50 (défaut : 20)

cURL

curl "https://lyricsfree.app/api/v1/artists?page=1" \
  -H "Authorization: Bearer lf_votre_cle_api"

200 — Réponse

JSON-LD

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "numberOfItems": 18,
  "lf:page": 1,
  "lf:totalPages": 1,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "MusicGroup",
        "identifier": 3,
        "name": "Zeynab",
        "countryOfOrigin": "Bénin"
      }
    }
  ]
}

Languages

GET/api/v1/languagesLangues disponibles avec compteur

Retourne les langues pour lesquelles des chansons publiées existent, avec le nombre de chansons par langue, triées par popularité décroissante.

cURL

curl "https://lyricsfree.app/api/v1/languages" \
  -H "Authorization: Bearer lf_votre_cle_api"

200 — Réponse

JSON-LD

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "numberOfItems": 3,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "Language",
        "name": "fon",
        "lf:songCount": 87
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "Language",
        "name": "fr",
        "lf:songCount": 23
      }
    }
  ]
}

Valeurs de référence

Valeurs acceptées pour les paramètres genre et country.

Genres musicaux

Valeur (param)	Label	Catégorie
`pop`	Pop	Urbain
`hiphop`	Hip-Hop / Rap	Urbain
`rnb`	R&B / Soul	Urbain
`electronic`	Électronique	Urbain
`dance`	Dance / House	Urbain
`trap`	Trap	Urbain
`rock`	Rock	Rock
`metal`	Metal	Rock
`indie`	Indie / Alternatif	Rock
`folk`	Folk / Acoustique	Rock
`varietes`	Variétés	Rock
`afrobeats`	Afrobeats	Afrique
`afropop`	Afropop	Afrique
`coupe-decale`	Coupé-Décalé	Afrique
`amapiano`	Amapiano	Afrique
`highlife`	Highlife	Afrique
`mbalax`	Mbalax	Afrique
`ndombolo`	Ndombolo / Rumba	Afrique
`traditionnel`	Traditionnel	Afrique
`reggae`	Reggae	Caraïbes
`dancehall`	Dancehall	Caraïbes
`salsa`	Salsa	Caraïbes
`latin`	Latin / Reggaeton	Caraïbes
`zouk`	Zouk / Kompa	Caraïbes
`jazz`	Jazz	Classique
`blues`	Blues	Classique
`classique`	Classique	Classique
`gospel`	Gospel	Spirituel
`religieux`	Religieux / Chant liturgique	Spirituel
`bande-originale`	Bande originale / OST	Autre
`autre`	Autre	Autre

Pays

Le paramètre country attend le nom du pays (pas le code ISO). La correspondance est insensible à la casse.

Valeur (param)	Code ISO
`Bénin`	BJ
`Côte d'Ivoire`	CI
`Sénégal`	SN
`Mali`	ML
`Burkina Faso`	BF
`Togo`	TG
`Nigeria`	NG
`Ghana`	GH
`Cameroun`	CM
`Congo (RDC)`	CD
`Congo (Brazzaville)`	CG
`Guinée`	GN
`Niger`	NE
`Gabon`	GA
`France`	FR