Parcourir la documentation
Guides
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 objectif | Solution |
|---|---|
| Résumer les propos ou créer un index textuel | Lisez 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’audio | Choisissez une sortie audio seule, sans piste vidéo inutilisée par votre application. |
| Afficher un court extrait | Dé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éo | Choisissez 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.
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio_video",
"output_format": "mp4",
"video_quality": "<=720"
}
}Un fichier audio à écouter ou à traiter.
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio",
"output_format": "mp3"
}
}Un extrait MP4 de 00:00:05 à 00:00:10. Adaptez ces repères à la vidéo choisie.
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio_video",
"output_format": "mp4",
"video_quality": "<=720",
"start_at": "00:00:05",
"end_at": "00:00:10"
}
}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écision | Mise en pratique |
|---|---|
| Estimer le coût | Utilisez 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éel | Lisez 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. |
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --jsonPré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.
| Identifiant | Rôle |
|---|---|
| Clé FlashData | Soumettre 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’application | Lire l’objet privé ou en donner l’accès à un utilisateur autorisé. |
{
"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"
}chmod 600 storage.jsonSoumettre 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.
(
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
)(
set -eu
umask 077
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
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" | curl --fail-with-body --silent --show-error --max-time 70 \
--request POST 'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Content-Type: application/json' \
--data-binary @- --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.
(
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.
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id' download-submission.json)
flashdata jobs wait "$JOB_ID"
)(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
STATUS_URL=$(jq -er '.links[] | select(.rel == "self") | .href' download-submission.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
"$STATUS_URL" --output job.json
jq '.job | {id, status, error}' job.json
)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.
(
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
)(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
jq -e '.job.status == "completed"' job.json >/dev/null
RESULTS_URL=$(jq -er '.links[] | select(.rel == "results") | .href' download-submission.json)
# Get the signed JSON URL without forwarding the API key to storage.
STORAGE_URL=$(curl --fail-with-body --silent --show-error --max-time 30 \
--header "X-API-Key: $FLASHDATA_API_KEY" --header 'Accept: application/json' \
--output /dev/null --write-out '%{redirect_url}' "$RESULTS_URL")
: "${STORAGE_URL:?No signed result URL was returned}"
curl --fail-with-body --silent --show-error --compressed --max-time 70 \
"$STORAGE_URL" --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.
(
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.
(
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é
| Situation | Action 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 stockage | Lisez 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 403 | Vé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. |
flashdata runs show download-001 --jsonPréciser à votre agent la sortie et les critères de livraison
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.