# API-Übersicht | AudioDN Docs

> Basis-URL, Authentifizierung, Anfrageformat und Fehlerbehandlung für die AudioDN-API.

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

---

# API-Übersicht

Alles, was Sie wissen müssen, bevor Sie Ihre erste API-Anfrage stellen.

## Basis-URL

Alle API-Endpunkte sind mit `/v1/` präfixiert. Verwenden Sie die folgende Basis-URL für alle Anfragen:

```
https://api.audiodelivery.net/v1/
```

## Authentifizierung

Die meisten API-Anfragen erfordern Authentifizierung über einen Bearer-Token im Header `Authorization`. Wenn Sie ADN-Webkomponenten mit einem Client-Side-API-Key verwenden, übernehmen die Komponenten die Authentifizierung automatisch — dieser Abschnitt gilt für direkte API-Anfragen.

```
Authorization: Bearer your_api_key_here
```

Einige Upload- und Wiedergabe-Endpunkte werden durch eine Session-ID in der URL statt durch einen Bearer-Token autorisiert und nehmen keinen `Authorization`\-Header entgegen: `GET /v1/upload_session/:upload_session_id`, `POST /v1/upload/:upload_session_id/track` und `GET /v1/play/:play_session_id/:play_track_id`. Jeder ist in seiner Endpunkt-Referenz vermerkt.

### API-Key-Typen

| Key-Typ | Anwendungsfall | Sicherheit |
| --- | --- | --- |
| API Access | Server-zu-Server-Anfragen — Sessions erstellen, Tracks verwalten, Varianten konfigurieren | Geheim halten. Niemals in clientseitigem Code exponieren. |
| Client-Side | Webkomponenten und Mobile-Apps — Audio abspielen, Dateien hochladen | Sicher im Front-End-Code. Nur auf Wiedergabe- und Upload-Operationen beschränkt. |
| Inline Share | Öffentliche Share-Links — direkte Weiterleitung zu einer einzelnen Track-Variante ohne Authorization-Header | Der Key steckt in der URL. Jeder mit dem Link kann streamen, bis Ablauf oder Löschung. Im Dashboard erstellt. Siehe [Inline Share](/docs/api/share). |
| URL Signing | Delivery-URLs auf Ihrem eigenen Server für öffentliche Tracks signieren — keine Wiedergabesession und kein Authorization-Header | Das Signing-Geheimnis bleibt serverseitig. Im Dashboard erstellt. Siehe [Signing Keys](/docs/api/signing-keys). |

#### API-Keys erstellen

Erstellen Sie Ihren ersten **API Access**\-Key auf der Seite **Settings** im [AudioDN-Dashboard](https://account.audiodeliverynetwork.com). Mit diesem Key können Sie anschließend **Client-Side**\-Keys (Player und Uploader) Server-zu-Server über [POST /v1/api\_key](/docs/api/api-keys) erzeugen. **Inline Share**\- und **URL Signing**\-Keys werden nicht über die API verwaltet — erstellen Sie sie unter **Settings → API Keys** im Dashboard.

## Anfrageformat

Alle Anfrage- und Antwortkörper verwenden JSON. Fügen Sie den Header `Authorization` bei jeder authentifizierten Anfrage hinzu (siehe Ausnahmen oben) und setzen Sie `Content-Type: application/json`, wenn Sie einen Anfragekörper senden. Hier ein Beispiel zum Erstellen einer Wiedergabesession auf jeder Plattform:

#### Beispielanfrage

    

```
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>;
}
```

## Antworten

Erfolgreiche Antworten enthalten `“ok”: true` zusammen mit den angeforderten Daten. Fehler geben `“ok”: false` mit einer Nachricht und einer eindeutigen Request-ID zum Debuggen zurück:

### Erfolg

```
{
"ok": true,
...
}
```

### Fehler

```
{
"ok": false,
"message": "Description of what went wrong",
"api_request_id": "uuid"
}
```

### HTTP-Statuscodes

| Code | Bedeutung |
| --- | --- |
| 200 | Erfolg |
| 400 | Ungültige Anfrage — prüfen Sie den Anfragekörper oder die Parameter |
| 401 | Nicht autorisiert — fehlender oder ungültiger API-Key |
| 403 | Verboten — der API-Key hat keine Berechtigung für diese Operation |
| 404 | Nicht gefunden — die Ressource existiert nicht oder ist nicht zugänglich |
| 410 | Gone — die Session ist abgelaufen |
| 500 | Interner Serverfehler — erneut versuchen oder Support kontaktieren |

## Paginierung

List-Endpunkte geben alle passenden Datensätze zurück. Bei großen Sammlungen filtern Sie nach `collection_id` oder `creator_id`, um die Ergebnisse einzugrenzen.

## IDs & Formate

Alle Ressourcen-IDs sind UUIDs (z. B. `04ea3a34-a0f7-45e8-a711-9c7274490e2e`). Zeitstempel werden als ISO-8601-Zeichenketten in UTC zurückgegeben.