# Sesiones de subida | Docs de AudioDN

> Endpoints de la API para crear sesiones de subida seguras. Habilita subidas de archivos de audio autenticadas y con tiempo limitado a colecciones.

Source: https://audiodeliverynetwork.com/es/docs/api/upload-sessions/

---

# Sesiones de subida

Las sesiones de subida permiten la subida por lotes de varias pistas a una colección. Opcionalmente puedes incluir un objeto anidado `track` al crear la sesión para crear también esa pista y recibir su URL de subida en la respuesta.

El `player_color` resuelto va acompañado de dos compañeros de solo lectura, `player_color_light` y `player_color_dark`, ajustados para permanecer legibles sobre fondos claros y oscuros respectivamente.

POST `/v1/upload_session`

Crea una nueva sesión de subida para subir pistas por lotes. Por defecto solo devuelve un upload\_session\_id — crea pistas vía POST /v1/upload/:upload\_session\_id/track. Opcionalmente incluye un objeto track anidado para crear también esa pista y recibir la URL de subida por pista en esta respuesta.

#### Parámetros

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `collection_id` | uuid | Obligatorio | ID de la colección. Obligatorio salvo que la clave API tenga alcance a una colección. |
| `creator_id` | uuid | Opcional | ID del creator |
| `organization_index` | string | Opcional | Índice de organización (nivel de sesión) |
| `metadata` | object | Opcional | Metadatos adicionales (nivel de sesión) |
| `expires_in` | number | Opcional | Duración de la sesión en segundos (predeterminado: 3600, mín: 60, máx: 86400) |
| `track` Pista opcional | object | Opcional | Cuando está presente, también crea esa pista y añade sus campos de subida a la respuesta. Campos anidados: file\_name, organization\_index, metadata. |
| `track.file_name` Pista opcional | string | Obligatorio | Nombre de archivo original de la pista. Obligatorio cuando track está presente. |
| `track.organization_index` Pista opcional | string | Opcional | Índice de organización de la pista (separado del campo a nivel de sesión). |
| `track.metadata` Pista opcional | object | Opcional | Metadatos de la pista (separados del campo a nivel de sesión). |

#### Ejemplo de solicitud

    

```
curl -X POST "https://api.audiodelivery.net/v1/upload_session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": "COLLECTION_ID",
  "expires_in": 7200
}'
```

```
const payload = {
  "collection_id": "COLLECTION_ID",
  "expires_in": 7200
};

const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/upload_session")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "collection_id": "COLLECTION_ID",
  "expires_in": 7200
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val body = """{
  "collection_id": "COLLECTION_ID",
  "expires_in": 7200
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/upload_session")
        .post(body)
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.post(
    Uri.parse("https://api.audiodelivery.net/v1/upload_session"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "collection_id": "COLLECTION_ID",
  "expires_in": 7200
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

Ejemplo con un `track` anidado opcional:

#### Ejemplo de solicitud

    

```
curl -X POST "https://api.audiodelivery.net/v1/upload_session" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection_id": "COLLECTION_ID",
  "track": {
    "file_name": "track-1.mp3"
  }
}'
```

```
const payload = {
  "collection_id": "COLLECTION_ID",
  "track": {
    "file_name": "track-1.mp3"
  }
};

const response = await fetch('https://api.audiodelivery.net/v1/upload_session', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/upload_session")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "collection_id": "COLLECTION_ID",
  "track": {
    "file_name": "track-1.mp3"
  }
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val body = """{
  "collection_id": "COLLECTION_ID",
  "track": {
    "file_name": "track-1.mp3"
  }
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/upload_session")
        .post(body)
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .addHeader("Content-Type", "application/json")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.post(
    Uri.parse("https://api.audiodelivery.net/v1/upload_session"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "collection_id": "COLLECTION_ID",
  "track": {
    "file_name": "track-1.mp3"
  }
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

#### Pista anidada opcional

Incluye un objeto anidado `track` para crear esa pista durante la creación de la sesión — la respuesta añade los mismos handles de subida que el endpoint por pista. Aún puedes añadir más pistas después con `POST /v1/upload/:upload_session_id/track`. Para flujos solo por lotes, omite `track` y crea cada pista con ese endpoint.

#### Respuesta

```
{
"ok": true,
"upload_session_id": "uuid",
"upload_session": {
  "id": "uuid",
  "creator_id": "uuid | null",
  "collection_id": "uuid",
  "organization_index": "string | null",
  "metadata": {},
  "expires_at": "string"
},
"player_color": "string | null",
"player_color_light": "string | null",
"player_color_dark": "string | null",
"expires_at": "string"
}
```

#### Respuesta cuando incluyes `track`

```
{
"ok": true,
"upload_session_id": "uuid",
"upload_session": {
  "id": "uuid",
  "creator_id": "uuid | null",
  "collection_id": "uuid",
  "organization_index": "string | null",
  "metadata": {},
  "expires_at": "string"
},
"player_color": "string | null",
"player_color_light": "string | null",
"player_color_dark": "string | null",
"expires_at": "string",
"track_id": "uuid",
"track": {
  "id": "uuid",
  "index": "string",
  "path": "string",
  "upload_url": "string"
},
"track_upload": {
  "method": "PUT",
  "upload_url": "string",
  "ttl": 0,
  "expires_at": "string"
},
"track_cover_upload": {
  "method": "POST",
  "upload_url": "string",
  "ttl": 0,
  "expires_at": "string"
}
}
```

GET `/v1/upload_session/:upload_session_id`

Recupera detalles de una sesión de subida. No se requiere autenticación — el ID de sesión actúa como credencial.

#### Parámetros

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `upload_session_id` | uuid | Obligatorio | El ID de la sesión de subida (parámetro de ruta) |

#### Ejemplo de solicitud

    

```
curl -X GET "https://api.audiodelivery.net/v1/upload_session/SESSION_ID"
```

```
const response = await fetch('https://api.audiodelivery.net/v1/upload_session/SESSION_ID');

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/upload_session/SESSION_ID")!)
    request.httpMethod = "GET"

    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/upload_session/SESSION_ID")

        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.get(Uri.parse("https://api.audiodelivery.net/v1/upload_session/SESSION_ID"));
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

#### Respuesta

```
{
"ok": true,
"upload_session_id": "uuid",
"upload_session": {
  "id": "uuid",
  "creator_id": "uuid | null",
  "collection_id": "uuid",
  "organization_index": "string | null",
  "metadata": {},
  "expires_at": "string"
},
"player_color": "string | null",
"player_color_light": "string | null",
"player_color_dark": "string | null",
"expires_at": "string"
}
```

POST `/v1/upload/:upload_session_id/track`

Crea una nueva pista dentro de una sesión de subida y devuelve su URL de subida por pista. Llama a esto una vez por archivo (incluyendo cualquier archivo adicional tras un track anidado opcional al crear la sesión). No se requiere autenticación — el ID de sesión actúa como credencial.

#### Parámetros

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `upload_session_id` | uuid | Obligatorio | El ID de la sesión de subida (parámetro de ruta) |
| `file_name` | string | Obligatorio | Nombre de archivo original de la pista |
| `organization_index` | string | Opcional | Índice de organización |
| `metadata` | object | Opcional | Metadatos adicionales |

#### Ejemplo de solicitud

    

```
curl -X POST "https://api.audiodelivery.net/v1/upload/SESSION_ID/track" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "track-1.mp3"
}'
```

```
const payload = {
  "file_name": "track-1.mp3"
};

const response = await fetch('https://api.audiodelivery.net/v1/upload/SESSION_ID/track', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
```

```
import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/upload/SESSION_ID/track")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "file_name": "track-1.mp3"
}
"""
    request.httpBody = bodyJSON.data(using: .utf8)
    let (data, _) = try await URLSession.shared.data(for: request)
    let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
    // use json
}
```

```
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody

val client = OkHttpClient()

suspend fun performRequest(): String = withContext(Dispatchers.IO) {
    val body = """{
  "file_name": "track-1.mp3"
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/upload/SESSION_ID/track")
        .post(body)
        .addHeader("Content-Type", "application/json")
        .build()
    val response = client.newCall(request).execute()
    response.body?.string() ?: error("Empty response body")
}
```

```
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<Map<String, dynamic>> performRequest() async {
  final response = await http.post(
    Uri.parse("https://api.audiodelivery.net/v1/upload/SESSION_ID/track"),
    headers: {
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "file_name": "track-1.mp3"
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}
```

#### Respuesta

```
{
"ok": true,
"api_request_id": "uuid",
"upload_session_id": "uuid",
"track_id": "uuid",
"track": {
  "id": "uuid",
  "index": "string",
  "path": "string",
  "upload_url": "string"
},
"upload_session": {
  "id": "uuid",
  "creator_id": "uuid | null",
  "collection_id": "uuid",
  "organization_index": "string | null",
  "metadata": {},
  "expires_at": "string"
},
"track_upload": {
  "method": "PUT",
  "upload_url": "string",
  "ttl": 0,
  "expires_at": "string"
},
"track_cover_upload": {
  "method": "POST",
  "upload_url": "string",
  "ttl": 0,
  "expires_at": "string"
}
}
```