# Vue d'ensemble de l'API | Docs AudioDN

> URL de base, authentification, format des requêtes et gestion des erreurs pour l

Source: https://audiodeliverynetwork.com/fr/docs/api/

---

# 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](/docs/api/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](/docs/api/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](https://account.audiodeliverynetwork.com). 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](/docs/api/api-keys). 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"
  ]
}'
```

```
const payload = {
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
};

const response = await fetch('https://api.audiodelivery.net/v1/play_session/collection', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/play_session/collection")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val body = """{
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/play_session/collection")
        .post(body)
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.post(
    Uri.parse("https://api.audiodelivery.net/v1/play_session/collection"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "collection_id": "COLLECTION_ID",
  "variants": [
    "hq",
    "lq"
  ]
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

## 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.