Oferta de lanzamiento: Los planes Creator y Business tienen descuento por tiempo limitado. Ver precios

Sesiones de reproducción

Las sesiones de reproducción gestionan la reproducción de audio de colecciones, pistas o playlists.

El player_color resuelto de cada pista va acompañado de dos compañeros de solo lectura: player_color_light (ajustado para permanecer legible sobre un fondo claro) y player_color_dark (ajustado para un fondo oscuro), para que tu player pueda elegir el adecuado según su tema.

POST /v1/play_session/:scope

Crea una nueva sesión de reproducción para una colección o pista.

Parámetros

Nombre Tipo Obligatorio Descripción
scope string Obligatorio "collection" o "track" (parámetro de ruta). "playlist" está reservado para una versión futura y actualmente devuelve 400.
variants array of strings Obligatorio Lista no vacía de índices de variante para la sesión de reproducción (p. ej. ["hq", "lq"]).
collection_id uuid Obligatorio ID de la colección cuando el scope es "collection". Obligatorio salvo que la clave API tenga alcance a una colección.
track_id uuid Obligatorio ID de la pista cuando el scope es "track". Obligatorio salvo que la clave API tenga alcance a una pista.
is_downloadable boolean Opcional Solicita que las pistas de esta sesión sean descargables. Solo se respeta cuando la clave API también permite descargas (se configura por clave en el panel). El valor almacenado de la sesión es api_key.is_downloadable AND esta solicitud, así que una clave que prohíbe descargas siempre gana — el endpoint de descarga devolverá 403.
expires_in number Opcional Duración de la sesión en segundos (predeterminado: 3600, mín: 60, máx: 86400)

Ejemplo de solicitud

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
}'

Respuesta

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

El campo first_track incluye los datos completos de reproducción de la primera pista (URLs de streaming firmadas, niveles de forma de onda, imagen de portada y variantes) para que tu player pueda renderizar de inmediato sin una segunda llamada a la API. Usa GET /v1/play/:session_id/:track_id para obtener pistas adicionales bajo demanda.

GET /v1/play_session/:play_session_id

Recupera detalles de una sesión de reproducción

Parámetros

Nombre Tipo Obligatorio Descripción
play_session_id uuid Obligatorio El ID de la sesión de reproducción (parámetro de ruta)

Ejemplo de solicitud

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

Respuesta

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

El campo first_track incluye los datos completos de reproducción de la primera pista para que tu player pueda renderizar de inmediato sin una segunda llamada a la API.

GET /v1/play/:play_session_id/:play_track_id

Recupera detalles de una pista concreta dentro de una sesión de reproducción. No se requiere autenticación: el ID de sesión actúa como token bearer.

Parámetros

Nombre Tipo Obligatorio Descripción
play_session_id uuid Obligatorio El ID de la sesión de reproducción (parámetro de ruta)
play_track_id uuid Obligatorio El ID de la pista dentro de la sesión (parámetro de ruta)

Respuesta

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

Descarga una variante concreta de una pista. Solo disponible cuando el is_downloadable almacenado de la sesión es true (es decir, la clave API permite descargas y la sesión las solicitó); en caso contrario devuelve 403. No se requiere autenticación.

Parámetros

Nombre Tipo Obligatorio Descripción
play_session_id uuid Obligatorio El ID de la sesión de reproducción (parámetro de ruta)
play_track_id uuid Obligatorio El ID de la pista dentro de la sesión (parámetro de ruta)
variant_index string Obligatorio El índice/identificador de la variante a descargar (parámetro de ruta)

Respuesta

Devuelve una URL de descarga firmada de corta duración (30s). El cuerpo de la respuesta es JSON (no el archivo de audio); navega a download.url para obtener el archivo. La URL se sirve con Content-Disposition: attachment para que el navegador guarde el archivo en lugar de reproducirlo en línea. Si la sesión no es descargable, el endpoint devuelve 403 con un mensaje de error.

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