Browse documentation
Guides
Choose the right media output, control what you download, and turn a completed job into a usable private file.
On this page
Start with what your task needs
| Your goal | Use |
|---|---|
| Summarize spoken content or build a text index | Read an existing transcript first. Download audio only when your workflow needs the audio itself, such as a separate speech-to-text step. |
| Process speech or audio | Audio-only output. Avoid carrying a video track your application does not use. |
| Show a short excerpt | Set start_at and end_at. Check that both are within the source video's duration. |
| Play or process video | MP4 with audio and a resolution cap suited to your application; the example uses <=720. |
Save the output you want
Choose one tab and save its entire request as download-request.json. Change video_id for your source. The submission commands below read this file, so choosing audio or a clip changes the actual request.
A complete video with audio, capped at 720p.
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio_video",
"output_format": "mp4",
"video_quality": "<=720"
}
}An audio file for listening or further audio processing.
{
"source": "youtube_download",
"video_id": "jNQXAC9IVRw",
"params": {
"download_type": "audio",
"output_format": "mp3"
}
}An MP4 excerpt from 00:00:05 to 00:00:10. Use times that match your selected video.
{
"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"
}
}Check owner access and byte-based pricing
Use Bash and jq, plus a saved CLI profile or FLASHDATA_API_KEY for HTTP. The key needs youtube_download permission. Download requires owner access; temporary trial access does not include it. CLI examples use your default profile; add --profile NAME to every command if yours is named.
| Decision | Apply it this way |
|---|---|
| Estimate cost | Use the returned creditsPerTb and bytesPerUnit with your estimated output bytes. Download pricing is not a fixed charge per request. |
| Control scope | Choose audio, a clip or a resolution cap before submission. Apply job-count and spending rules in your application. |
| Record the actual charge | Read usage from the completed delivery. Admission may hold credits before the upload settles; current balance is not a per-job spending cap. |
flashdata account balance --json
flashdata account pricing --source youtube_download --json
flashdata account limits --jsonUse a private destination for each output
Save storage.json privately with your real destination values. Keep it outside source control. Use a distinct object_prefix for each video/output version; reusing a prefix for different outputs makes application records harder to reconcile.
| Credential | Purpose |
|---|---|
| FlashData key | Submit the download and read its job and delivery JSON. |
| Storage upload credential | Write media to the intended bucket and prefix. |
| Application storage identity | Read the private object or issue access to an authorized user. |
{
"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.jsonSubmit the saved request once
Run one tab after saving both files. The command injects storage.json through stdin and saves download-submission.json. Keep this receipt. With CLI, retain the same run ID for a retry; use a new ID only for an intentional new output. HTTP submissions do not use the CLI's local run journal.
(
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
)Validate first with the CLI
Expect ok: true and data.dryRun: true. This checks input and FlashData access without submitting a job; it does not prove the upload credentials can write to your 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
)Wait for the existing job
The submission receipt is not the media file. CLI waits; the HTTP command reads status once. Repeat the read within your deadline until completed or failed. A local timeout does not cancel the server job.
(
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
)Read the delivery record, then access the media
After completed, retrieve delivery.json using the same path you used to submit. The signed result URL retrieves JSON; results[0].file_url identifies the media in your storage. A private file_url needs your storage read identity or a link issued by your 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
)Check what was delivered
Expect one file location, a positive file_size, an MD5 and usage. Record file_size for the delivered object; downloaded_bytes is a transfer field, not a replacement for the final charge in 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
)Verify a local copy from S3
Set OBJECT_KEY to the delivered media key from file_url, including its prefix. Use AWS CLI with read access, jq and OpenSSL. This saves media.mp4 or media.mp3 according to your chosen request and checks its size and checksum without overwriting an existing local file.
(
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'
)Recover from the stage that failed
| What happened | Next action |
|---|---|
| Submission timed out with no confirmed job ID | Inspect the saved CLI run or request history. Keep the original input and do not automatically submit again. |
| Job accepted; waiting timed out | Read or recover the same job. Do not create another download to continue waiting. |
| Upload failed | Read the job error and fix destination settings or write access before intentionally retrying. |
| Media read returned 403 | Check storage read permissions or the application-issued link. The FlashData API key does not unlock S3. |
| Signed result JSON expired | Read the job result endpoint again while the result is retained. Stored media follows your bucket's lifecycle. |
flashdata runs show download-001 --jsonGive your agent the output and delivery criteria
Use my saved owner access and configured private storage.
Read download-request.json for the video and output; do not change them silently.
Check Download pricing and available credits against the approved task budget.
Submit once, save the run/job ID, then read that job to completion.
Save the delivery record. Verify the stored object's size and MD5 before processing it.
Report the object location, chosen format, verification result and actual usage.
If submission is uncertain, inspect saved work; do not create replacement access or another download.
Keep storage credentials private. Share media only through the application's configured access controls.