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

Resumen de la API

Todo lo que necesitas saber antes de hacer tu primera solicitud a la API.

URL base

Todos los endpoints de la API llevan el prefijo /v1/. Usa la siguiente URL base para todas las solicitudes:

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

Autenticación

La mayoría de las solicitudes a la API requieren autenticación mediante un token Bearer en la cabecera Authorization. Si usas los componentes web de ADN con una clave API Client-Side, los componentes gestionan la autenticación automáticamente — esta sección se aplica a las solicitudes directas a la API.

Authorization: Bearer your_api_key_here

Algunos endpoints de subida y reproducción se autorizan con un ID de sesión en la URL en lugar de un token Bearer, y no llevan cabecera Authorization: GET /v1/upload_session/:upload_session_id, POST /v1/upload/:upload_session_id/track y GET /v1/play/:play_session_id/:play_track_id. Cada uno se indica en su referencia de endpoint.

Tipos de clave API

Tipo de claveCaso de usoSeguridad
API AccessSolicitudes de servidor a servidor — crear sesiones, gestionar pistas, configurar variantesMantenla en secreto. Nunca la expongas en código del cliente.
Client-SideComponentes web y apps móviles — reproducir audio, subir archivosSegura para incluir en código front-end. Limitada solo a operaciones de reproducción y subida.
Inline ShareEnlaces de compartir públicos — redirigen directamente a una sola variante de pista sin cabecera AuthorizationLa clave está en la URL. Cualquiera con el enlace puede reproducir hasta que caduque o se elimine. Se crea en el panel. Ver Inline Share.
URL SigningFirmar URLs de entrega en tu propio servidor para pistas públicas — sin sesión de reproducción ni cabecera AuthorizationEl secreto de firma permanece en el servidor. Se crea en el panel. Ver Signing Keys.

Crear claves API

Crea tu primera clave API Access desde la página de Settings en el panel de AudioDN. Con esa clave puedes generar después claves Client-Side (player y uploader) de servidor a servidor vía POST /v1/api_key. Las claves Inline Share y URL Signing no se gestionan a través de la API — créalas desde Settings → API Keys en el panel.

Formato de solicitud

Todos los cuerpos de solicitud y respuesta usan JSON. Incluye la cabecera Authorization en cada solicitud autenticada (ver las excepciones anteriores) y establece Content-Type: application/json al enviar un cuerpo de solicitud. Aquí un ejemplo creando una sesión de reproducción en todas las plataformas:

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

Respuestas

Las respuestas correctas incluyen “ok”: true junto con los datos solicitados. Los errores devuelven “ok”: false con un mensaje y un ID de solicitud único para depuración:

Éxito

{
"ok": true,
...
}

Error

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

Códigos de estado HTTP

CódigoSignificado
200Éxito
400Solicitud incorrecta — revisa el cuerpo o los parámetros de la solicitud
401No autorizado — clave API ausente o no válida
403Prohibido — la clave API no tiene permiso para esta operación
404No encontrado — el recurso no existe o no es accesible
410Gone — la sesión ha caducado
500Error interno del servidor — reintenta o contacta con soporte

Paginación

Los endpoints de listado devuelven todos los registros coincidentes. Para colecciones grandes, filtra por collection_id o creator_id para acotar los resultados.

IDs y formatos

Todos los IDs de recurso son UUIDs (p. ej. 04ea3a34-a0f7-45e8-a711-9c7274490e2e). Las marcas de tiempo se devuelven como cadenas ISO 8601 en UTC.