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. |
| 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. |
API-Keys erstellen
Erstellen Sie Ihren ersten API Access-Key auf der Seite Settings im AudioDN-Dashboard. Mit diesem Key können Sie anschließend Client-Side-Keys (Player und Uploader) Server-zu-Server über POST /v1/api_key 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"
]
}' 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.