Vue d’ensemble de l’API
Tout ce que vous devez savoir avant de faire votre première requête API.
URL de base
Tous les points de terminaison de l’API sont préfixés par /v1/. Utilisez l’URL de base suivante pour toutes les requêtes :
https://api.audiodelivery.net/v1/ Authentification
La plupart des requêtes API nécessitent une authentification via un jeton Bearer dans l’en-tête Authorization. Si vous utilisez les composants web ADN avec une clé API côté client, les composants gèrent l’authentification automatiquement — cette section s’applique aux requêtes API directes.
Authorization: Bearer your_api_key_here Quelques points de terminaison d’envoi et de lecture sont autorisés par un identifiant de session dans l’URL au lieu d’un jeton Bearer, et ne prennent pas d’en-tête Authorization : GET /v1/upload_session/:upload_session_id, POST /v1/upload/:upload_session_id/track, et GET /v1/play/:play_session_id/:play_track_id. Chacun est indiqué dans sa référence de point de terminaison.
Types de clés API
| Type de clé | Cas d’usage | Sécurité |
|---|---|---|
| API Access | Requêtes de serveur à serveur — créer des sessions, gérer les pistes, configurer les variantes | Gardez-la secrète. Ne l’exposez jamais dans le code côté client. |
| Client-Side | Composants web et applications mobiles — lire l’audio, envoyer des fichiers | Peut être incluse dans le code front-end en toute sécurité. Limitée aux opérations de lecture et d’envoi uniquement. |
| Inline Share | Liens de partage public — redirection directe vers une seule variante de piste sans en-tête Authorization | La clé est dans l’URL. Quiconque possède le lien peut streamer jusqu’à expiration ou suppression. Créée dans le tableau de bord. Voir Inline Share. |
| URL Signing | Signer les URL de livraison sur votre propre serveur pour les pistes publiques — aucune session de lecture ni en-tête Authorization | Le secret de signature reste côté serveur. Créée dans le tableau de bord. Voir Signing Keys. |
Création des clés API
Créez votre première clé API Access depuis la page Settings dans le tableau de bord AudioDN. Avec cette clé, vous pouvez ensuite générer des clés Client-Side (lecteur et envoyeur) de serveur à serveur via POST /v1/api_key. Les clés Inline Share et URL Signing ne sont pas gérées via l’API — créez-les depuis Settings → API Keys dans le tableau de bord.
Format des requêtes
Tous les corps de requête et de réponse utilisent JSON. Incluez l’en-tête Authorization sur chaque requête authentifiée (voir les exceptions ci-dessus), et définissez Content-Type: application/json lors de l’envoi d’un corps de requête. Voici un exemple de création d’une session de lecture sur chaque plateforme :
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"
]
}' Réponses
Les réponses réussies incluent “ok”: true avec les données demandées. Les erreurs renvoient “ok”: false avec un message et un identifiant de requête unique pour le débogage :
Succès
{
"ok": true,
...
} Erreur
{
"ok": false,
"message": "Description of what went wrong",
"api_request_id": "uuid"
} Codes de statut HTTP
| Code | Signification |
|---|---|
| 200 | Succès |
| 400 | Mauvaise requête — vérifiez le corps de la requête ou les paramètres |
| 401 | Non autorisé — clé API manquante ou invalide |
| 403 | Interdit — la clé API n’a pas la permission pour cette opération |
| 404 | Non trouvé — la ressource n’existe pas ou n’est pas accessible |
| 410 | Disparu — la session a expiré |
| 500 | Erreur interne du serveur — réessayez ou contactez le support |
Pagination
Les points de terminaison de liste renvoient tous les enregistrements correspondants. Pour les grandes collections, filtrez par collection_id ou creator_id pour limiter les résultats.
Identifiants et formats
Tous les identifiants de ressources sont des UUID (par ex. 04ea3a34-a0f7-45e8-a711-9c7274490e2e). Les horodatages sont renvoyés comme des chaînes ISO 8601 en UTC.