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 clave | Caso de uso | Seguridad |
|---|---|---|
| API Access | Solicitudes de servidor a servidor — crear sesiones, gestionar pistas, configurar variantes | Mantenla en secreto. Nunca la expongas en código del cliente. |
| Client-Side | Componentes web y apps móviles — reproducir audio, subir archivos | Segura para incluir en código front-end. Limitada solo a operaciones de reproducción y subida. |
| Inline Share | Enlaces de compartir públicos — redirigen directamente a una sola variante de pista sin cabecera Authorization | La 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 Signing | Firmar URLs de entrega en tu propio servidor para pistas públicas — sin sesión de reproducción ni cabecera Authorization | El 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ódigo | Significado |
|---|---|
| 200 | Éxito |
| 400 | Solicitud incorrecta — revisa el cuerpo o los parámetros de la solicitud |
| 401 | No autorizado — clave API ausente o no válida |
| 403 | Prohibido — la clave API no tiene permiso para esta operación |
| 404 | No encontrado — el recurso no existe o no es accesible |
| 410 | Gone — la sesión ha caducado |
| 500 | Error 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.