Variantes

Une variante est une recette réutilisable qui définit un résultat à générer à partir de chaque envoi — un transcodage, un aperçu, une forme d’onde ou une analyse — et chaque résultat est stocké comme un fichier de piste sur la piste. Les variantes à l’échelle de l’organisation (appliquées à chaque envoi) sont créées sur le site web. Vous pouvez aussi ajouter une variante spécifique à une piste à une seule piste déjà traitée via l’API — pratique pour générer un format supplémentaire ou un clip d’aperçu à la demande.

GET /v1/variant

Renvoie une liste de variantes pour une organisation

Paramètres

Nom	Type	Obligatoire	Description
`limit`	number	Facultatif	Nombre maximum de variantes à renvoyer
`offset`	number	Facultatif	Nombre de variantes à ignorer

Exemple de requête

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

const response = await fetch('https://api.audiodelivery.net/v1/variant', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  }
});

const data = await response.json();

import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/variant")!)
    request.httpMethod = "GET"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    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/variant")
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .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/variant"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
    },
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

Réponse

{
"ok": true,
"api_request_id": "uuid",
"count": 0,
"variants": [
  {
    "id": "uuid",
    "organization_id": "uuid",
    "variant_type_id": "string",
    "props": {}
  }
]
}

GET /v1/variant/:variant_id

Renvoie les détails d'une variante spécifique

Paramètres

Nom	Type	Obligatoire	Description
`variant_id`	uuid	Obligatoire	L'identifiant de la variante à récupérer (paramètre de chemin)

Exemple de requête

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

const response = await fetch('https://api.audiodelivery.net/v1/variant/VARIANT_ID', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
  }
});

const data = await response.json();

import Foundation

func performRequest() async throws {
    var request = URLRequest(url: URL(string: "https://api.audiodelivery.net/v1/variant/VARIANT_ID")!)
    request.httpMethod = "GET"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    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/variant/VARIANT_ID")
        .addHeader("Authorization", "Bearer YOUR_API_KEY")
        .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/variant/VARIANT_ID"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
    },
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

Réponse

{
"ok": true,
"api_request_id": "uuid",
"variant_id": "uuid",
"variant": {
  "id": "uuid",
  "organization_id": "uuid",
  "variant_type_id": "string",
  "props": {}
}
}

POST /v1/track/:track_id/variant

Ajoute une variante spécifique à une piste déjà traitée et met en file son traitement

Ajoute un nouveau fichier de piste à une piste existante. La piste passe à processing pendant la génération du nouveau fichier, puis revient automatiquement à ready. Seuls transcode et preview sont pris en charge via ce point de terminaison, et seuls les codecs de sortie avec perte sont autorisés (aac, mp3, ogg, opus). Les paramètres de codec sont optionnels et par défaut aac à 128 kbps.

Paramètres communs

Nom	Type	Obligatoire	Description
`track_id`	uuid	Obligatoire	La piste à laquelle ajouter la variante (paramètre de chemin)
`variant_type_id`	string	Obligatoire	'transcode' (fichier pleine longueur) ou 'preview' (court clip). Détermine quel jeu de paramètres ci-dessous s'applique
`index`	string	Obligatoire	Nom de livraison pour la variante (2–64 caractères, lettres/chiffres/_/-). Ne doit pas entrer en collision avec une variante d'organisation ou de piste existante

Lorsque `variant_type_id` est `“transcode”`

Format alternatif pleine longueur. Exemple : { "variant_type_id": "transcode", "index": "mp3", "codec": "mp3", "bitrate": 192 }.

Paramètres de transcodage

Nom	Type	Obligatoire	Description
`codec`	string	Facultatif	Codec de sortie : aac (par défaut), mp3, ogg ou opus. Les codecs sans perte (flac, alac) ne sont pas autorisés
`bitrate`	number	Facultatif	Débit de sortie en kbps, 12–320 (par défaut 128). Ne s'applique qu'aux codecs qui utilisent un débit
`is_stereo`	boolean	Facultatif	Conserver la sortie stéréo (par défaut true). Lorsque false, la sortie est mixée en mono
`is_strip_tags`	boolean	Facultatif	Supprimer les balises de métadonnées de la sortie (par défaut true)
`is_strip_cover`	boolean	Facultatif	Supprimer la pochette intégrée de la sortie (par défaut true)

Lorsque `variant_type_id` est `“preview”`

Court clip découpé dans la piste. Accepte aussi les Paramètres de transcodage ci-dessus pour l’audio de sortie (le codec par défaut est aac / 128). Le début du clip est toujours un pourcentage de la durée de la piste (preview_start_percent).

Paramètres d'aperçu

Nom	Type	Obligatoire	Description
`preview_type`	string	Facultatif	'seconds' (par défaut) ou 'percent' — comment la longueur du clip est mesurée
`preview_seconds`	number	Facultatif	Lorsque preview_type est 'seconds' : longueur du clip en secondes (par défaut 60)
`preview_min_percent`	number	Facultatif	Lorsque preview_type est 'seconds' : longueur minimale du clip en pourcentage de la durée, 0–100 (par défaut 0)
`preview_max_percent`	number	Facultatif	Lorsque preview_type est 'seconds' : longueur maximale du clip en pourcentage de la durée, 0–100 (par défaut 50)
`preview_percent`	number	Facultatif	Lorsque preview_type est 'percent' : longueur du clip en pourcentage de la durée, 0–100 (par défaut 25)
`preview_min_seconds`	number	Facultatif	Lorsque preview_type est 'percent' : longueur minimale du clip en secondes (par défaut 0)
`preview_max_seconds`	number	Facultatif	Lorsque preview_type est 'percent' : longueur maximale du clip en secondes (par défaut 90)
`preview_start_percent`	number	Facultatif	Où le clip commence, en pourcentage de la durée totale, 0–100 (par défaut 25). Toujours utilisé quel que soit preview_type

Exemple de requête

curl -X POST "https://api.audiodelivery.net/v1/track/TRACK_ID/variant" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "variant_type_id": "preview",
  "index": "preview",
  "preview_type": "seconds",
  "preview_seconds": 3,
  "preview_min_percent": 0,
  "preview_max_percent": 100,
  "preview_start_percent": 25
}'

const payload = {
  "variant_type_id": "preview",
  "index": "preview",
  "preview_type": "seconds",
  "preview_seconds": 3,
  "preview_min_percent": 0,
  "preview_max_percent": 100,
  "preview_start_percent": 25
};

const response = await fetch('https://api.audiodelivery.net/v1/track/TRACK_ID/variant', {
  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/track/TRACK_ID/variant")!)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    let bodyJSON = """
{
  "variant_type_id": "preview",
  "index": "preview",
  "preview_type": "seconds",
  "preview_seconds": 3,
  "preview_min_percent": 0,
  "preview_max_percent": 100,
  "preview_start_percent": 25
}
"""
    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 = """{
  "variant_type_id": "preview",
  "index": "preview",
  "preview_type": "seconds",
  "preview_seconds": 3,
  "preview_min_percent": 0,
  "preview_max_percent": 100,
  "preview_start_percent": 25
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://api.audiodelivery.net/v1/track/TRACK_ID/variant")
        .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/track/TRACK_ID/variant"),
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: jsonEncode({
  "variant_type_id": "preview",
  "index": "preview",
  "preview_type": "seconds",
  "preview_seconds": 3,
  "preview_min_percent": 0,
  "preview_max_percent": 100,
  "preview_start_percent": 25
}),
  );
  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw Exception('Request failed: ${response.statusCode}');
  }
  return jsonDecode(response.body) as Map<String, dynamic>;
}

Réponse

{
"ok": true,
"api_request_id": "uuid",
"track_id": "uuid",
"variant_id": "uuid",
"job_id": "uuid",
"variant": {
  "id": "uuid",
  "organization_id": "uuid",
  "track_id": "uuid",
  "variant_type_id": "preview",
  "index": "preview",
  "props": {
    "preview_type": "seconds",
    "preview_seconds": 3,
    "preview_min_percent": 0,
    "preview_max_percent": 100,
    "preview_start_percent": 25,
    "codec": "aac",
    "bitrate": 128,
    "is_stereo": true,
    "is_strip_tags": true,
    "is_strip_cover": true
  }
}
}

Variantes

Paramètres

Exemple de requête

Réponse

Paramètres

Exemple de requête

Réponse

Paramètres communs

Lorsque variant_type_id est “transcode”

Paramètres de transcodage

Lorsque variant_type_id est “preview”

Paramètres d'aperçu

Exemple de requête

Réponse

Lorsque `variant_type_id` est `“transcode”`

Lorsque `variant_type_id` est `“preview”`