Launch-Aktion: Die Pläne Creator und Business sind für begrenzte Zeit rabattiert. Preise ansehen

Wiedergabesessions

Wiedergabesessions verwalten die Audio-Wiedergabe für Sammlungen, Tracks oder Playlists.

Die aufgelöste player_color jedes Tracks wird von zwei schreibgeschützten Begleitfeldern begleitet: player_color_light (angepasst für Lesbarkeit auf hellem Hintergrund) und player_color_dark (angepasst für dunklen Hintergrund), damit Ihr Player die passende Farbe für sein Theme wählen kann.

POST /v1/play_session/:scope

Erstellt eine neue Wiedergabesession für eine Sammlung oder einen Track.

Parameter

Name Typ Erforderlich Beschreibung
scope string Erforderlich "collection" oder "track" (Pfadparameter). "playlist" ist für eine zukünftige Version reserviert und gibt derzeit 400 zurück.
variants array of strings Erforderlich Nicht leere Liste von Varianten-Indexes für die Wiedergabesession (z. B. ["hq", "lq"]).
collection_id uuid Erforderlich Sammlungs-ID, wenn scope "collection" ist. Erforderlich, sofern der API-Key nicht auf eine Sammlung beschränkt ist.
track_id uuid Erforderlich Track-ID, wenn scope "track" ist. Erforderlich, sofern der API-Key nicht auf einen Track beschränkt ist.
is_downloadable boolean Optional Fordert an, dass Tracks dieser Session downloadbar sind. Wird nur berücksichtigt, wenn der API-Key ebenfalls Downloads erlaubt (pro Key im Dashboard gesetzt). Der gespeicherte Session-Wert ist api_key.is_downloadable AND diese Anfrage — ein Key, der Downloads verbietet, gewinnt immer — der Download-Endpunkt gibt dann 403 zurück.
expires_in number Optional Session-Dauer in Sekunden (Standard: 3600, min: 60, max: 86400)

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"
  ],
  "expires_in": 3600
}'

Antwort

{
"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"
}

Das Feld first_track enthält die vollständigen Wiedergabedaten des ersten Tracks (signierte Streaming-URLs, Wellenform-Levels, Coverbild und Varianten), damit Ihr Player sofort rendern kann, ohne einen zweiten API-Aufruf. Nutzen Sie GET /v1/play/:session_id/:track_id, um weitere Tracks bei Bedarf abzurufen.

GET /v1/play_session/:play_session_id

Ruft Details einer Wiedergabesession ab

Parameter

Name Typ Erforderlich Beschreibung
play_session_id uuid Erforderlich Die ID der Wiedergabesession (Pfadparameter)

Beispielanfrage

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

Antwort

{
"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" } } ]
}
}

Das Feld first_track enthält die vollständigen Wiedergabedaten des ersten Tracks, damit Ihr Player sofort rendern kann, ohne einen zweiten API-Aufruf.

GET /v1/play/:play_session_id/:play_track_id

Ruft Details eines bestimmten Tracks in einer Wiedergabesession ab. Keine Authentifizierung erforderlich — die Session-ID dient als Bearer-Token.

Parameter

Name Typ Erforderlich Beschreibung
play_session_id uuid Erforderlich Die ID der Wiedergabesession (Pfadparameter)
play_track_id uuid Erforderlich Die ID des Tracks in der Session (Pfadparameter)

Antwort

{
"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

Lädt eine bestimmte Variante eines Tracks herunter. Nur verfügbar, wenn das gespeicherte is_downloadable der Session true ist (d. h. der API-Key erlaubt Downloads und die Session hat sie angefordert); sonst 403. Keine Authentifizierung erforderlich.

Parameter

Name Typ Erforderlich Beschreibung
play_session_id uuid Erforderlich Die ID der Wiedergabesession (Pfadparameter)
play_track_id uuid Erforderlich Die ID des Tracks in der Session (Pfadparameter)
variant_index string Erforderlich Der Index/die Kennung der herunterzuladenden Variante (Pfadparameter)

Antwort

Gibt eine kurzlebige signierte Download-URL zurück (30 s). Der Antwortkörper ist JSON (nicht die Audiodatei); navigieren Sie zu download.url, um die Datei abzurufen. Die URL wird mit Content-Disposition: attachment ausgeliefert, damit der Browser die Datei speichert statt sie inline abzuspielen. Wenn die Session nicht downloadbar ist, gibt der Endpunkt 403 mit einer Fehlermeldung zurück.

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