# FlashData YouTube Download API

Pobierz YouTube wideo lub audio do pamięci masowej w chmurze. Wybierz rozdzielczość, format i czas trwania klipu, a następnie śledź asynchroniczną pracę poprzez ukończenie.

Odniesienie kanoniczne: https://flashdata.dev/pl/docs/sources/youtube_download
Przegląd: 2026-10-23

Punkt końcowy: POST https://data.flashdata.dev/v1/queries
Uwierzytelnianie: X-API-Key: YOUR_API_KEY
Tryby: [Async](https://flashdata.dev/pl/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/pl/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md)

Wymagane zezwolenie na korzystanie ze źródła: youtube_download

Zastąp YOUR_API_KEY kluczem API, który posiada to pozwolenie źródłowe i dostępne kredyty. Uruchom żądania na serwerze lub hoście agenta.

[Konfiguracja uwierzytelniania](https://flashdata.dev/pl/docs/guides/headers-and-authentication/reference.md)

[Pobierz jeden film i zweryfikuj dostawę](https://flashdata.dev/pl/docs/guides/download-video-recipe/reference.md)

[API pobierania filmów z YouTube — przykłady w Pythonie](https://github.com/flashdatadev/youtube-video-download-api)

<a id="quickstart"></a>

## Wyślij wniosek

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_download",
    "video_id": "jNQXAC9IVRw",
    "params": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_download",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "download_type": "audio_video",
    "video_quality": "<=720",
    "output_format": "mp4",
    "storage": {
      "storage_type": "s3",
      "storage_url": "your-media-bucket",
      "access_key": "YOUR_ACCESS_KEY",
      "secret_key": "YOUR_SECRET_KEY",
      "region": "us-east-1"
    }
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parametry

<a id="parameters-group-0"></a>

### Treść żądania

| Parametr | Rodzaj | Wymagane | Domyślnie | Opis |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Tak | — | Ustaw na youtube_download.  |
| <a id="parameter-video_id"></a> video_id | string | Tak | Nieustawione | 11- znak YouTube wideo ID, takich jak FUfGcZ092b0. Akceptuje litery, liczby, podkreślenia i mifeny. Minimalna długość: 11. Maksymalna długość: 11. Wzór: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Tak | — | Settings dla tego wniosku.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Nie | Nieustawione | Async i tylko partia. Publiczne ukończenie HTTPS URL na porcie 443, do znaków 2,048. Brak danych uwierzytelniających użytkownika lub fragmentu URL. Omit, użyj null lub pustego łańcucha bez powiadomienia. W partii, ustawić to na każdym zapytaniu, na zewnątrz params.  |

<a id="parameters-group-1"></a>

### Wideo i audio

| Parametr | Rodzaj | Wymagane | Domyślnie | Opis |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-download_type"></a> params.download_type | string | Nie | "audio_video" | audio_video łączy wideo i audio; wideo wybiera tylko wideo; audio wybiera tylko audio. Dozwolone: "audio_video", "video", "audio". Minimalna długość: 1. Maksymalna długość: 11. |
| <a id="parameter-params-video_quality"></a> params.video_quality | string | Nie | "<=720" | Wybór rozdzielczości wideo. Omit do pobrania tylko audio. Dozwolone: "best", "worst", "<=144", "==144", ">=144", "<=360", "==360", ">=360", "<=480", "==480", ">=480", "<=720", "==720", ">=720", "<=1080", "==1080", ">=1080", "<=1440", "==1440", ">=1440", "<=2160", "==2160", ">=2160", "<=4320", "==4320", ">=4320". Minimalna długość: 1. Maksymalna długość: 40. |
| <a id="parameter-params-fps"></a> params.fps | string | Nie | Nieustawione | Ograniczenie frame- rate: > =, < = lub = = po którym następuje wartość od 1 do 240. Omit do pobrania tylko audio. Minimalna długość: 1. Maksymalna długość: 6. Wzór: ^(?:>=\|<=\|==)(?:[1-9]\d?\|1\d\d\|2[0-3]\d\|240)$ |
| <a id="parameter-params-audio_language"></a> params.audio_language | string | Nie | "default" | Wybór ścieżki dźwiękowej. Dotyczy audio_video i audio. Dozwolone: "default", "original". Minimalna długość: 1. Maksymalna długość: 8. |
| <a id="parameter-params-audio_quality"></a> params.audio_quality | string | Nie | "best" | Audio- tylko bitrate w kbps, lub najlepiej. Wybory numeryczne muszą być przesyłane jako struny. Omit do pobrania wideo. Dozwolone: "best", "320", "256", "192", "128". Minimalna długość: 1. Maksymalna długość: 10. |
| <a id="parameter-params-output_format"></a> params.output_format | string | Nie | mp4 (video) / m4a (audio) | Wideo: mp4, webm lub mkv. Audio: m4a, mp3 lub opus. Dozwolone: "mp4", "webm", "mkv", "m4a", "mp3", "opus". Minimalna długość: 1. Maksymalna długość: 10. |
| <a id="parameter-params-yt_dlp_format"></a> params.yt_dlp_format | string | Nie | Nieustawione | Zaawansowany selektor formatu, od 1 do znaków 1,024 po przycinaniu spacji białych. Znaki kontrolne są odrzucane. Overrides video_quality, fps i audio_language, których wartości są następnie ignorowane; format wyjściowy i wyciskanie nadal mają zastosowanie. Minimalna długość: 1. Maksymalna długość: 1024. |
| <a id="parameter-params-upload_metadata"></a> params.upload_metadata | boolean | Nie | false | Wyślij plik metadanych JSON obok pliku mediów w Twoim magazynie.  |

<a id="parameters-group-2"></a>

### Wycinanie

| Parametr | Rodzaj | Wymagane | Domyślnie | Opis |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-start_at"></a> params.start_at | string | Nie | Nieustawione | Clip start in H: MM: SS or HH: MM: SS format, od 00:00:00 do 12:00:00. Domyślne wartości 00:00:00, gdy tylko jest dostępny end_at. Minimalna długość: 1. Maksymalna długość: 8. Wzór: ^\d{1,2}:[0-5]\d:[0-5]\d$ |
| <a id="parameter-params-end_at"></a> params.end_at | string | Nie | Nieustawione | Koniec klipu w H: MM: SS lub HH: MM: SS format, do 12:00:00. Musi być później niż start_at. Minimalna długość: 1. Maksymalna długość: 8. Wzór: ^\d{1,2}:[0-5]\d:[0-5]\d$ |

<a id="parameters-group-3"></a>

### Miejsce przechowywania

| Parametr | Rodzaj | Wymagane | Domyślnie | Opis |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-storage"></a> params.storage | object | Tak | — | Miejsce przeznaczenia wypełnionych plików medialnych. Dopuszczalne są tylko wymienione pola pamięci.  |
| <a id="parameter-params-storage-storage_type"></a> params.storage.storage_type | string | Tak | — | Dostawca przechowywania: s3, s3_compatible, oss, gcs, azure, cos, bos lub tos.  |
| <a id="parameter-params-storage-storage_url"></a> params.storage.storage_url | string | Tak | — | Niepuste wiadro lub nazwa pojemnika, do znaków 1,024. Otoczenie Whitespace jest usuwane. Dla s3 użyj poprawnej nazwy wiadra AWS bez ścieżki URL lub folderu; foldery należą do object_prefix.  |
| <a id="parameter-params-storage-object_prefix"></a> params.storage.object_prefix | string | Nie | "YYYYMMDD" | Przedrostek z kluczem obiektowym, znaki 1 do 512. Każdy segment oddzielony od slash- akceptuje litery, cyfry, kropki, podkreślenia i hypheny ASCII; puste segmenty, i.. są odrzucane. Żadnego cięcia. Otaczające się białe spacje i jeden ślad ukośnik są usuwane. RRRRMMDD używa daty wysłania UTC, w tym w archive/YYYYMMDD.  |
| <a id="parameter-params-storage-access_key"></a> params.storage.access_key | string | Nie | — | Klucz dostępu dla S3, S3- kompatybilny z OSS, COS, BOS lub TOS; połączony z secret_key.  |
| <a id="parameter-params-storage-secret_key"></a> params.storage.secret_key | string | Nie | — | Sekretny klucz dla S3, S3- kompatybilny, OSS, COS, BOS lub TOS.  |
| <a id="parameter-params-storage-endpoint_url"></a> params.storage.endpoint_url | string | Nie | — | Ogólny punkt końcowy HTTPS dla przechowywania zgodnego z S3- lub OSS. COS, BOS i TOS pochodzą z regionu.  |
| <a id="parameter-params-storage-region"></a> params.storage.region | string | Nie | — | Wymagane dla COS, BOS i TOS; również dostarczyć dla S3 i S3- pobieranie. Nazwy wiader COS zawierają APID.  |
| <a id="parameter-params-storage-service_account"></a> params.storage.service_account | object | Nie | — | Konto usługowe GCS: project_id, client_email i PEM private_key.  |
| <a id="parameter-params-storage-account_name"></a> params.storage.account_name | string | Nie | — | Nazwa konta Azure. Należy użyć nazwy kontenera w storage_url.  |
| <a id="parameter-params-storage-sas_token"></a> params.storage.sas_token | string | Nie | — | Kontener Azure SAS z możliwością zapisu wraz z wygaśnięciem i podpisem.  |

<a id="response"></a>

## Przeczytaj wynik

Po zakończeniu zadania, zapisz JSON z linka wyników jako response.json. Zapisz to jako read-response.py i uruchom python read-response.py. Odczytuje szczegóły plików bez pobierania mediów lub innych wniosków.

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {name: result.get(name) for name in (
    "file_url", "file_size", "md5", "duration", "output_format"
)}
# Use your storage credentials to access the media at file_url.
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Składanie próbek

Nagrywany przykład; pola i liczby zależą od źródła i żądanego wejścia.
```json
{
  "id": "job_d265c693-950e-40bf-a13e-a432044d99ba",
  "source": "youtube_download",
  "status": "pending",
  "usage": {
    "credits": 0
  },
  "created_at": "2026-09-16T07:51:13.139Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/jobs/job_d265c693-950e-40bf-a13e-a432044d99ba/results",
      "method": "GET"
    }
  ]
}
```

## Pola odpowiedzi

| Pole | Rodzaj | Opis |
| --- | --- | --- |
| id | string | Pobierz zadanie ID. |
| source | string | youtube_download. |
| status | string | w oczekiwaniu na przyjęcie pracy. |
| created_at | string | Czas tworzenia miejsc pracy w formacie ISO 8601. |
| usage.credits | number | 0 w momencie składania. Pliki do pobrania są pobierane przez dostarczoną ilość danych po zakończeniu. |
| links | array | Podążaj za własnym linkiem dla statusu zadania i za linkiem wyników dla zakończonego wyjścia. |
| links[].rel | string | siebie lub wyników. |
| links[].href | string | URL do zapytania tym samym klawiszem API. |
| links[].method | string | GET. |

- Pliki do pobrania działają jako praca w tle. Odpowiedź na zgłoszenie zawiera zadanie ID; nie zawiera pliku multimedialnego. Postępuj zgodnie ze statusem zadania do zakończenia, a następnie odzyskaj wynik opisujący pliki dostarczone do magazynu. Prześlij pliki do /v1/queries lub /v1/queries/batch; /v1/queries/realtime nie akceptuje wniosków o pobranie.

## Formaty odpowiedzi

Odpowiedzi używać JSON domyślnie. Wybierz inny format z tymi opcjonalnymi nagłówkami.

- Accept: application/json (domyślne) lub text/plain. Prosty tekst przedstawia te same pola w czytelnym, wciętym układzie.
- X-Respond-With: markdown. Pozostawić nieustawione dla oryginalnych pól. Markdown współpracuje z każdym z formatów odpowiedzi.

Markdown formatuje manifest pobierania; pliki medialne zachowują swój oryginalny format. Wpływy i status pracy wspierają tylko Accept.

Poniższe pola opisują domyślną odpowiedź JSON.

[Przykłady formularzy zapytań i odpowiedzi](https://flashdata.dev/pl/docs/guides/response-formats/reference.md#completed-results)

<a id="storage"></a>

## Miejsce przechowywania

Single- job i Batch pobieranie wymagają params.storage; Bulk pobiera się za pomocą options.storage. storage_url to nazwa pojemnika lub wiadra. Dane uwierzytelniające z dostępem do zapisu i przechowywać je na serwerze.

### s3

Dostawa access_key i secret_key z dostępem do zapisu. Ustaw region na obszar wiadra AWS.

```json
{
  "storage_type": "s3",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "us-east-1"
}
```

### s3_compatible

Supply access_key, secret_key i publiczny HTTPS endpoint_url. Ustaw region zgodnie z wymaganiami dostawcy; Cloudflare R2 wykorzystuje auto.

```json
{
  "storage_type": "s3_compatible",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com",
  "region": "auto"
}
```

### azure

Supply account_name and sas_token, kontener SAS z pozwoleniem na zapis (sp zawiera w), zasób sr = c, expire se, wersja sv i sig podpis. storage_url jest nazwą kontenera. Nie wysyłaj endpoint_url, access_key ani secret_key.

```json
{
  "storage_type": "azure",
  "storage_url": "your-media-container",
  "account_name": "yourstorageaccount",
  "sas_token": "sv=2023-11-03&sr=c&sp=w&se=2099-01-01T00%3A00%3A00Z&sig=YOUR_SAS_SIGNATURE"
}
```

### bos

Supply access_key, secret_key i region: bj, su lub hkg. Punkt końcowy uzyskuje się z regionu, gdy go pominięto. Użyj nazwy wiadra bez kropek.

```json
{
  "storage_type": "bos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "bj"
}
```

### cos

Supply access_key, secret_key i region ap- *, takich jak ap- hongkong. storage_url musi zawierać przyrostek APID. Nie wysyłaj endpoint_url; pochodzi z regionu.

```json
{
  "storage_type": "cos",
  "storage_url": "your-media-bucket-1234567890",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "ap-hongkong"
}
```

### gcs

Dostawa service_account z project_id, client_email (a .gserviceaccount.com adres) oraz PEM private_key z Twojego konta serwisowego. Konto musi mieć pisemny dostęp do wiadra. Nie wysyłaj access_key, secret_key, regionu lub endpoint_url.

```json
{
  "storage_type": "gcs",
  "storage_url": "your-media-bucket",
  "service_account": {
    "project_id": "your-project-id",
    "client_email": "uploader@your-project-id.iam.gserviceaccount.com",
    "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n"
  }
}
```

### oss

Dostawa access_key, secret_key i publiczne HTTPS endpoint_url.

```json
{
  "storage_type": "oss",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "endpoint_url": "https://oss-cn-hongkong.aliyuncs.com"
}
```

### tos

Supply access_key, secret_key i region z cn-, ap-, eu- lub us- prefix. Punkt końcowy uzyskuje się z regionu, gdy go pominięto. Użyj nazwy wiadra bez kropek.

```json
{
  "storage_type": "tos",
  "storage_url": "your-media-bucket",
  "access_key": "YOUR_ACCESS_KEY",
  "secret_key": "YOUR_SECRET_KEY",
  "region": "cn-beijing"
}
```

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## Podstawy API

Konstruktor wniosków i przykłady powyżej korzystają z parametrów tego źródła. Użyj poniższych przykładów Python i cURL dla wspólnych etapów składania, statusu i rezultatu. Batch to obiekt JSON zawierający zapytania; każdy element zwraca swoje własne zadanie ID.

- [Async wniosek i odbiór](https://flashdata.dev/pl/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Sprawdzić status pracy](https://flashdata.dev/pl/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Pobieranie zakończonych wyników](https://flashdata.dev/pl/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON wnioski](https://flashdata.dev/pl/docs/reference/batch-and-bulk/reference.md#batch)
- [API przetwarzania Bulk](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md)
- [Zbuduj przepływ pracy Bulk dla tego źródła](https://flashdata.dev/pl/docs/reference/bulk-processing/reference.md?source=youtube_download#playground)
- [Klient OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Powiadomienia o zakończeniu

- [Otrzymuj i weryfikuj ukończone haki](https://flashdata.dev/pl/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Rozwiązywanie problemów

- [Błędy i kody statusu](https://flashdata.dev/pl/docs/errors/reference.md#status-codes)
- [Kiedy spróbować ponownie](https://flashdata.dev/pl/docs/errors/reference.md#retries)

<a id="delivery"></a>

## Dostarczanie plików

Pobieranie nie obsługuje czasu rzeczywistego.

Media są przesyłane do skonfigurowanej pamięci masowej; wynik JSON opisuje te pliki. Prywatne media wykorzystują uwierzytelnianie pamięci masowej. JSON wyniki wygasają 24 godziny po zakończeniu; media przestrzegają zasad przechowywania.

## Powiązane API

- [YouTube Metadane wideo API](https://flashdata.dev/pl/docs/sources/youtube_metadata/reference.md)
- [YouTube Transcript API](https://flashdata.dev/pl/docs/sources/youtube_transcript/reference.md)
