Offre de lancement : Les forfaits Creator et Business sont réduits pour une durée limitée. Voir les tarifs

Sessions de lecture

Les sessions de lecture gèrent la lecture audio pour les collections, pistes ou playlists.

Le player_color résolu de chaque piste est accompagné de deux compagnons en lecture seule : player_color_light (ajusté pour rester lisible sur un fond clair) et player_color_dark (ajusté pour un fond sombre), afin que votre lecteur puisse choisir le bon pour son thème.

POST /v1/play_session/:scope

Crée une nouvelle session de lecture pour une collection ou une piste.

Paramètres

Nom Type Obligatoire Description
scope string Obligatoire "collection" ou "track" (paramètre de chemin). "playlist" est réservé à une version future et renvoie actuellement 400.
variants array of strings Obligatoire Liste non vide d'index de variantes pour la session de lecture (par ex. ["hq", "lq"]).
collection_id uuid Obligatoire Identifiant de la collection lorsque scope est "collection". Requis sauf si la clé API est limitée à une collection.
track_id uuid Obligatoire Identifiant de la piste lorsque scope est "track". Requis sauf si la clé API est limitée à une piste.
is_downloadable boolean Facultatif Demande que les pistes de cette session soient téléchargeables. Ceci n'est honoré que lorsque la clé API autorise aussi les téléchargements (défini par clé dans le tableau de bord). La valeur stockée de la session est api_key.is_downloadable AND cette requête, donc une clé qui interdit les téléchargements l'emporte toujours — le point de terminaison de téléchargement renverra 403.
expires_in number Facultatif Durée de la session en secondes (par défaut : 3600, min : 60, max : 86400)

Exemple de requête

curl -X POST "https://api.audiodelivery.net/v1/play_session/collection" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ],
  "expires_in": 3600
}'

Réponse

{
"ok": true,
"play_session_id": "uuid",
"play_session": {
  "id": "uuid",
  "creator_id": "uuid | null",
  "variants": ["string"],
  "is_downloadable": false,
  "expires_at": "string"
},
"tracks": [
  { "id": "uuid", "index": "string", "duration": 0, "order": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null" }
],
"first_track": {
  "track_id": "uuid",
  "cover_image": {
    "icon": { "type": "icon", "width": 80, "height": 80, "url": "string" },
    "small": { "type": "small", "width": 200, "height": 200, "url": "string" },
    "regular": { "type": "regular", "width": 400, "height": 400, "url": "string" }
  },
  "track": {
    "id": "uuid",
    "index": "string",
    "duration": 0,
    "player_title": "string | null",
    "player_subtitle": "string | null",
    "player_color": "string | null",
    "player_color_light": "string | null",
    "player_color_dark": "string | null",
    "theme": [],
    "file_name": "string",
    "info": {},
    "organization_index": "string | null",
    "order": 0,
    "metadata": {},
    "is_dark": false
  },
  "levels": { "levels": [ 0, 0.5, 1 ] },
  "variants": [
    { "path": "string", "url": "string", "variant": { "index": "string" } }
  ]
},
"expires_at": "string"
}

Le champ first_track inclut les données de lecture complètes de la première piste (URL de streaming signées, niveaux de forme d’onde, image de couverture et variantes) afin que votre lecteur puisse s’afficher immédiatement sans un second appel API. Utilisez GET /v1/play/:session_id/:track_id pour récupérer des pistes supplémentaires à la demande.

GET /v1/play_session/:play_session_id

Récupère les détails d'une session de lecture

Paramètres

Nom Type Obligatoire Description
play_session_id uuid Obligatoire L'identifiant de la session de lecture (paramètre de chemin)

Exemple de requête

curl -X GET "https://api.audiodelivery.net/v1/play_session/SESSION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Réponse

{
"ok": true,
"play_session_id": "uuid",
"play_session": {
  "id": "uuid",
  "creator_id": "uuid | null",
  "variants": ["string"],
  "is_downloadable": false,
  "expires_at": "string"
},
"tracks": [
  { "id": "uuid", "index": "string", "duration": 0, "order": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null" }
],
"first_track": {
  "track_id": "uuid",
  "cover_image": { "icon": {}, "small": {}, "regular": {} },
  "track": { "id": "uuid", "index": "string", "duration": 0, "player_title": "string | null", "player_subtitle": "string | null", "player_color": "string | null", "player_color_light": "string | null", "player_color_dark": "string | null", "theme": [], "file_name": "string", "info": {}, "organization_index": "string | null", "order": 0, "metadata": {}, "is_dark": false },
  "levels": { "levels": [] },
  "variants": [ { "path": "string", "url": "string", "variant": { "index": "string" } } ]
}
}

Le champ first_track inclut les données de lecture complètes de la première piste afin que votre lecteur puisse s’afficher immédiatement sans un second appel API.

GET /v1/play/:play_session_id/:play_track_id

Récupère les détails d'une piste spécifique dans une session de lecture. Aucune authentification requise - l'identifiant de session sert de jeton bearer.

Paramètres

Nom Type Obligatoire Description
play_session_id uuid Obligatoire L'identifiant de la session de lecture (paramètre de chemin)
play_track_id uuid Obligatoire L'identifiant de la piste dans la session (paramètre de chemin)

Réponse

{
"ok": true,
"play_session_id": "uuid",
"track_id": "uuid",
"play_session": {
  "id": "uuid",
  "variants": ["string"],
  "is_downloadable": false,
  "expires_at": "string"
},
"cover_image": {
  "icon": { "type": "icon", "width": 80, "height": 80, "url": "string" },
  "small": { "type": "small", "width": 200, "height": 200, "url": "string" },
  "regular": { "type": "regular", "width": 400, "height": 400, "url": "string" }
},
"track": {
  "id": "uuid",
  "index": "string",
  "duration": 0,
  "player_title": "string | null",
  "player_subtitle": "string | null",
  "player_color": "string | null",
  "player_color_light": "string | null",
  "player_color_dark": "string | null",
  "theme": [],
  "file_name": "string",
  "info": {},
  "organization_index": "string | null",
  "order": 0,
  "metadata": {},
  "is_dark": false
},
"levels": { "levels": [ 0, 0.5, 1 ] },
"variants": [
  { "path": "string", "url": "string", "variant": { "index": "string" } }
]
}
GET /v1/play/:play_session_id/:play_track_id/:variant_index/download

Télécharge une variante spécifique d'une piste. Disponible uniquement lorsque le is_downloadable stocké de la session est true (c.-à-d. que la clé API autorise les téléchargements et que la session les a demandés) ; sinon renvoie 403. Aucune authentification requise.

Paramètres

Nom Type Obligatoire Description
play_session_id uuid Obligatoire L'identifiant de la session de lecture (paramètre de chemin)
play_track_id uuid Obligatoire L'identifiant de la piste dans la session (paramètre de chemin)
variant_index string Obligatoire L'index/identifiant de la variante à télécharger (paramètre de chemin)

Réponse

Renvoie une URL de téléchargement signée de courte durée (30 s). Le corps de la réponse est du JSON (pas le fichier audio) ; naviguez vers download.url pour récupérer le fichier. L’URL est servie avec Content-Disposition: attachment pour que le navigateur enregistre le fichier au lieu de le lire en ligne. Si la session n’est pas téléchargeable, le point de terminaison renvoie 403 avec un message d’erreur.

{
"ok": true,
"play_session_id": "uuid",
"track_id": "uuid",
"download": {
  "variant": "string",
  "url": "string"
}
}