Aller au contenu
FR
Obtenir une clé API
Parcourir la documentation

Guides

Bonnes pratiques : téléchargement YouTube

Choisissez le format adapté, maîtrisez ce que vous téléchargez et transformez une tâche terminée en fichier privé utilisable.

Sur cette page

Partir du besoin de votre application

Votre objectifSolution
Résumer les propos ou créer un index textuelLisez d’abord une transcription existante. Téléchargez l’audio uniquement si votre workflow en a besoin, par exemple pour une étape de reconnaissance vocale distincte.
Traiter la parole ou l’audioChoisissez une sortie audio seule, sans piste vidéo inutilisée par votre application.
Afficher un court extraitDéfinissez start_at et end_at. Vérifiez que les deux valeurs se situent dans la durée de la vidéo source.
Lire ou traiter une vidéoChoisissez un MP4 avec audio et une résolution maximale adaptée à votre application ; l’exemple utilise <=720.

Enregistrer la sortie souhaitée

Choisissez un onglet et enregistrez sa requête complète dans download-request.json. Remplacez video_id par celui de votre vidéo. Les commandes ci-dessous lisent ce fichier : choisir l’audio ou un extrait modifie donc la requête envoyée.

Une vidéo complète avec audio, limitée à 720p.

download-request.json
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "output_format": "mp4",
    "video_quality": "<=720"
  }
}

Vérifier l’accès propriétaire et la tarification au volume

Utilisez Bash et jq, avec un profil CLI enregistré ou FLASHDATA_API_KEY pour HTTP. La clé doit disposer de la permission youtube_download. Le téléchargement nécessite un accès propriétaire ; l’accès d’essai temporaire ne l’inclut pas. Les exemples CLI utilisent le profil par défaut. Pour un profil nommé, ajoutez --profile NAME à chaque commande.

DécisionMise en pratique
Estimer le coûtUtilisez les valeurs renvoyées creditsPerTb et bytesPerUnit avec votre estimation du volume de sortie en octets. Le téléchargement n’est pas facturé à un tarif fixe par requête.
Limiter le travail demandéChoisissez l’audio seul, un extrait ou une résolution maximale avant l’envoi. Appliquez dans votre application les limites de nombre de tâches et de dépenses.
Enregistrer le coût réelLisez usage dans le résultat de livraison terminé. Des crédits peuvent être réservés à l’acceptation de la tâche, avant le règlement du transfert. Le solde disponible ne constitue pas un plafond de dépenses par tâche.
Vérifications gratuites · CLI
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --json

Prévoir une destination privée pour chaque sortie

Enregistrez storage.json dans un emplacement privé avec les paramètres réels de votre destination, sans l’ajouter au dépôt de code. Utilisez un object_prefix distinct pour chaque version de vidéo ou de sortie ; réutiliser un préfixe pour des sorties différentes complique leur rapprochement avec les enregistrements de votre application.

IdentifiantRôle
Clé FlashDataSoumettre le téléchargement et lire le JSON de la tâche et de la livraison.
Identifiants d’écriture du stockageÉcrire le média dans le bucket et sous le préfixe prévus.
Identité de stockage de l’applicationLire l’objet privé ou en donner l’accès à un utilisateur autorisé.
storage.json · S3
{
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1",
  "object_prefix": "media/video-001/mp4-720p-v1"
}
Linux / macOS · fichier privé
chmod 600 storage.json

Soumettre une seule fois la requête enregistrée

Exécutez un seul onglet après avoir enregistré les deux fichiers. La commande transmet storage.json par stdin et enregistre download-submission.json. Conservez ce reçu. Avec la CLI, gardez le même identifiant d’exécution pour réessayer ; créez-en un nouveau uniquement pour une nouvelle sortie voulue. Les requêtes HTTP n’utilisent pas le journal local des exécutions de la CLI.

Soumettre la sortie choisie
(
set -eu
umask 077
test ! -e download-submission.json || { echo 'Inspect the saved submission first.' >&2; exit 1; }
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async \
  --run-id download-001 --output download-submission.json
)

Valider d’abord avec la CLI

Le résultat attendu est ok: true et data.dryRun: true. Cette vérification contrôle les paramètres et l’accès FlashData sans soumettre de tâche ; elle ne confirme pas que les identifiants de stockage permettent d’écrire dans votre bucket.

Simulation gratuite
(
set -eu
PAYLOAD=$(jq -en --slurpfile request download-request.json --slurpfile storage storage.json '
  if ($request | length) != 1 or ($storage | length) != 1
      or ($storage[0] | type) != "object" or $request[0].source != "youtube_download"
  then error("Check download-request.json and storage.json")
  else $request[0] | .params.storage = $storage[0] end')
printf '%s' "$PAYLOAD" | flashdata query --input - --mode async --dry-run --json
)

Attendre la tâche existante

Le reçu de soumission n’est pas le fichier média. La CLI attend ; la commande HTTP lit l’état une seule fois. Répétez cette lecture dans le délai prévu jusqu’à completed ou failed. Un délai d’attente local dépassé n’annule pas la tâche sur le serveur.

Attendre la tâche enregistrée
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs wait "$JOB_ID"
)

Lire le résultat de livraison, puis accéder au média

Quand l’état est completed, récupérez delivery.json avec la même méthode que pour la soumission. L’URL de résultat signée renvoie du JSON ; results[0].file_url désigne le média dans votre stockage. Une file_url privée nécessite votre identité de lecture du stockage ou un lien émis par votre application.

Enregistrer delivery.json
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs result "$JOB_ID" --output delivery.json
jq '.results[0] | {file_url, file_size, md5, downloaded_bytes}' delivery.json
)

Vérifier la livraison

Le résultat doit contenir un emplacement de fichier, un file_size positif, un MD5 et usage. Enregistrez file_size pour l’objet livré. downloaded_bytes décrit le transfert et ne remplace pas le coût final indiqué dans usage.

Examiner delivery.json
(
set -eu
jq -e '.source == "youtube_download" and .status == "done"
  and (.results | length == 1) and (.results[0].file_size > 0)
  and (.results[0].md5 | test("^[a-fA-F0-9]{32}$"))' delivery.json >/dev/null
jq '{file: (.results[0] | {file_url, file_size, md5, duration, output_format}), usage}' delivery.json
)

Vérifier une copie locale depuis S3

Définissez OBJECT_KEY avec la clé du média livré indiquée dans file_url, préfixe compris. Utilisez AWS CLI avec un accès en lecture, jq et OpenSSL. La commande enregistre media.mp4 ou media.mp3 selon la requête choisie, puis vérifie sa taille et sa somme de contrôle sans écraser de fichier local existant.

Lecture S3 · aucune nouvelle requête FlashData
(
set -eu
# Requires AWS CLI configured for read access, jq and OpenSSL.
# Set OBJECT_KEY to the delivered media object's key from file_url.
: "${OBJECT_KEY:?Set the delivered S3 object key}"
BUCKET=$(jq -er '.storage_url' storage.json)
REGION=$(jq -er '.region' storage.json)
FORMAT=$(jq -er '.params.output_format' download-request.json)
case "$FORMAT" in mp4|mp3) ;; *) echo 'Choose a filename for this format.' >&2; exit 1 ;; esac
LOCAL_FILE="media.$FORMAT"
test ! -e "$LOCAL_FILE" || { echo 'Keep the existing local file.' >&2; exit 1; }
EXPECTED_BYTES=$(jq -er '.results[0].file_size' delivery.json)
EXPECTED_MD5=$(jq -er '.results[0].md5 | ascii_downcase' delivery.json)
aws s3 cp "s3://$BUCKET/$OBJECT_KEY" "$LOCAL_FILE" --region "$REGION" --only-show-errors
ACTUAL_BYTES=$(wc -c < "$LOCAL_FILE" | tr -d '[:space:]')
ACTUAL_MD5=$(openssl dgst -md5 "$LOCAL_FILE" | awk '{print $NF}')
test "$ACTUAL_BYTES" = "$EXPECTED_BYTES"
test "$ACTUAL_MD5" = "$EXPECTED_MD5"
echo 'Delivery verified'
)

Reprendre à l’étape qui a échoué

SituationAction suivante
Soumission interrompue sans identifiant de tâche confirméExaminez l’exécution CLI enregistrée ou l’historique des requêtes. Conservez les paramètres d’origine et ne soumettez pas automatiquement une nouvelle requête.
Tâche acceptée, délai d’attente dépasséConsultez ou reprenez la même tâche. Ne créez pas un autre téléchargement pour continuer à attendre.
Échec du transfert vers le stockageLisez l’erreur de la tâche et corrigez la destination ou l’accès en écriture avant de relancer volontairement la requête.
La lecture du média renvoie 403Vérifiez les permissions de lecture du stockage ou le lien émis par votre application. La clé API FlashData ne donne pas accès à S3.
L’URL signée du résultat JSON a expiréRelisez l’endpoint de résultat tant que celui-ci est conservé. Le média stocké suit le cycle de vie de votre bucket.
CLI · examiner l’exécution enregistrée
flashdata runs show download-001 --json

Préciser à votre agent la sortie et les critères de livraison

Consigne pour l’agent · fournir la vidéo, la destination et le budget
Utilisez mon accès propriétaire enregistré et mon stockage privé configuré.
Lisez download-request.json pour connaître la vidéo et la sortie demandées ; ne les modifiez pas sans le signaler.
Vérifiez les tarifs de téléchargement et les crédits disponibles par rapport au budget approuvé pour la tâche.
Soumettez une seule fois, enregistrez les identifiants d’exécution et de tâche, puis suivez cette tâche jusqu’à sa fin.
Enregistrez le résultat de livraison. Vérifiez la taille et le MD5 de l’objet stocké avant de le traiter.
Indiquez l’emplacement de l’objet, le format choisi, le résultat de la vérification et la consommation réelle.
Si la soumission est incertaine, examinez les opérations enregistrées ; ne créez ni nouvel accès ni autre téléchargement.
Gardez les identifiants de stockage privés. Partagez le média uniquement au moyen des contrôles d’accès configurés dans l’application.