# Avvio rapido Python SDK

Installare il Python SDK e stampare i risultati della ricerca con alcune linee di codice. Include esempi sincroni e asincroni.

Riferimento canonico: https://flashdata.dev/it/docs/guides/flashdata-python
Recensito: 2026-11-04 da FlashData

- [GitHub](https://github.com/flashdatadev/flashdata-python) — Fonte e riferimento SDK
- [Ottieni una chiave API](https://flashdata.dev/app/api-keys) — Creare una chiave nella console

<a id="application"></a>

## Fai la tua prima richiesta Python

Installare lo SDK, impostare il tasto API ed eseguire una ricerca. Le risposte sono dizionari Python per impostazione predefinita.

- [Riferimento Python SDK](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/api-reference.md)
- [PyPI](https://pypi.org/project/flashdata/1.1.0/)

<a id="install"></a>

### Installare la SDK

Richiede Python 3.10+. Eseguire questi comandi nella directory del progetto. Già utilizzando un ambiente virtuale? Installare flashdata==1.1.0 con il pitone di quell'ambiente -m pip invece.

#### Linux / macOS

##### Installa

```bash
python3 -m venv .venv
.venv/bin/python -m pip install "flashdata==1.1.0"
```


#### Windows PowerShell

##### Installa

```powershell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "flashdata==1.1.0"
```


- [Installare Python](https://www.python.org/downloads/)

<a id="key"></a>

### Autentico

Creare una chiave API con il permesso di ricerca Google o riutilizzare una chiave autorizzata. Impostarlo in questo terminale utilizzando il prompt nascosto qui sotto.

Salta il prompt se FLASHDATA_API_KEY è già impostato. Questi esempi leggono direttamente la variabile; non caricano i file .env.

#### Bash

##### Segnale chiave nascosta · Bash

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


#### PowerShell 7

##### Segnale chiave nascosta · PowerShell

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [Registrati](https://flashdata.dev/signup)
- [Aprire API Keys](https://flashdata.dev/app/api-keys)
- [Aprire Billing](https://flashdata.dev/app/billing)
- [Configurazione della prova dell'agente](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md)

<a id="query"></a>

### Esegui una ricerca

Salvare questo come quickstart.py, quindi eseguirlo con lo stesso ambiente virtuale. Fa una richiesta di ricerca Google per un massimo di cinque risultati e stampe titoli, URLs e crediti utilizzati.

#### quickstart.py

```python
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.google.search("battery recycling research", num=5)
    if response["status"] != "done":
        raise RuntimeError(response)
    for page in response["results"]:
        for hit in page.get("organic", []):
            print(hit["title"], hit["link"])
    print("Credits used:", response["usage"]["credits"])
```

#### Linux / macOS

##### Esegui

```bash
.venv/bin/python quickstart.py
```


#### Windows PowerShell

##### Esegui

```powershell
.\.venv\Scripts\python.exe quickstart.py
```



<a id="result"></a>

### Verifica il risultato

Lo script esce normalmente dopo il controllo dello stato. I titoli di origine previsti e URLs seguiti da Crediti utilizzati. Una lista organica vuota è una risposta valida; i risultati variano con la tua richiesta.

| Campo di applicazione | Uso |
| --- | --- |
| results[].organic[] | Google Cerca successi: titolo, link e snippet. Altre fonti hanno diversi campi di risultato. |
| usage.credits | Costo di questa richiesta. Fino a cinque risultati qui sono una richiesta di ricerca. |

#### Esempio di output

```text
Battery recycling research https://example.org/recycling
Credits used: 0.02
```


<a id="common-tasks"></a>

## Prova un'altra fonte di dati

Ogni scheda è uno script completo. Sostituire quickstart.py con un esempio ed eseguirlo con il comando dal passo 3. Ogni esecuzione presenta una nuova richiesta; la chiave ha bisogno del permesso di origine mostrato.

### Google News

Richiede google_news. Stampa i titoli dell'articolo e i link di origine da results[].news[].

#### quickstart.py

```python
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.google.news("battery recycling", num=5)
    if response["status"] != "done":
        raise RuntimeError(response)
    for page in response["results"]:
        for article in page.get("news", []):
            print(article.get("title"), article.get("link"))
```


### metadati YouTube

Richiede youtube_metadata. Stampa il titolo video, il canale e la durata in pochi secondi. Sostituire il video ID con uno che si desidera ispezionare.

#### quickstart.py

```python
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.youtube.metadata("dQw4w9WgXcQ", include_formats=False)
    if response["status"] != "done":
        raise RuntimeError(response)
    for video in response["results"]:
        print(video.get("title"), video.get("channel"))
        print("Seconds:", video.get("duration"))
```


### Trascrizione di YouTube

Richiede youtube_transcript. Stampa una trascrizione automatica inglese esistente da results[].fullText. Il video deve avere quella traccia; questa chiamata non genera o traduce le didascalie.

#### quickstart.py

```python
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.youtube.transcript("dQw4w9WgXcQ", language="en", auto=True)
    if response["status"] != "done":
        raise RuntimeError(response)
    for track in response["results"]:
        print(track.get("fullText", ""))
```


- [Tutti i metodi e i parametri di origine](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/sources/index.md)

<a id="features"></a>

## Che cosa supporta Python SDK

| Uso | Punti di ingresso SDK |
| --- | --- |
| google / youtube | Google Cerca, Notizie, Immagini, Shopping, Video e Luoghi; YouTube scoperta, metadati, didascalie, trascrizioni e dati del canale. |
| youtube.download | Invia un lavoro di consegna audio o video al tuo cloud storage. Richiede il permesso youtube_download e la configurazione di archiviazione; segui l'esempio di download completo qui sotto. |
| jobs / bulk | Salvare il lavoro accettato ID, attendere il completamento e recuperare i risultati. Utilizzare la rinfusa per i dataset video-ID più grandi e riprendere i lavori esistenti dopo un riavvio. |
| account | Leggi l'accesso, l'equilibrio, i prezzi, i limiti e l'utilizzo prima del lavoro ricorrente. Riutilizzare una chiave autorizzata dal tuo ambiente o negozio segreto. |
| respond_with / accept | Utilizzare respond_with="markdown" per Markdown in risposta["content"], o accettare="text/plain" per una stringa. I dizionari JSON sono i valori predefiniti. |

- [Esempio di download completo Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/examples/youtube_download.py)
- [Configurare lo storage di download](https://flashdata.dev/it/docs/guides/youtube-download-guide/reference.md)
- [Formati di risposta Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/response-formats.md)

<a id="asyncio"></a>

## Utilizzare la sincronizzazione

Sostituire quickstart.py con questa versione e utilizzare lo stesso comando run. AsyncFlashData espone le stesse risorse con attesa. Questo aspetta ancora una risposta di ricerca in tempo reale; mode="async" presenta invece un lavoro di sfondo lato server.

In Jupyter o un'applicazione con un ciclo di eventi in esecuzione, l'uso attendere principale() invece di asyncio.run(main()). Riutilizzare il cliente all'interno di quel ciclo di eventi.

### quickstart.py

```python
import asyncio
import os
from flashdata import AsyncFlashData

async def main():
    async with AsyncFlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
        response = await client.google.search("battery recycling research", num=5)
        if response["status"] != "done":
            raise RuntimeError(response)
        for page in response["results"]:
            for hit in page.get("organic", []):
                print(hit["title"], hit["link"])
        print("Credits used:", response["usage"]["credits"])

asyncio.run(main())
```

- [Configurazione client Async](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/client.md)

<a id="next"></a>

## Prossimo passo

- [Controllo account e risultati salvati](https://flashdata.dev/it/docs/guides/sdk-operations/reference.md)
- [Lavori di fondo e lotto](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/jobs.md)
- [Impostazioni dati Bulk](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/bulk.md)
- [Riferimento metodo SDK](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/api-reference.md)

<a id="errors"></a>

## Se un passo fallisce

| Problematiche | Risolto |
| --- | --- |
| ModuleNotFoundError | Installare ed eseguire con lo stesso interprete: .venv/bin/python -m pip mostra i dati flash (Windows: .\.venv\Scripts\python.exe -m pip mostra i dati flash). Non nominare il tuo script flashdata.py. |
| KeyError: FLASHDATA_API_KEY / 401 | Impostare un tasto API attivo nello stesso terminale. Un file .env da solo non è caricato da questo esempio. Utilizzare una chiave API, non un token MCP OAuth. |
| 403 | Concedere il permesso di origine richiesto dall'esempio a questa chiave. |
| 402 | Controllare Billing per i crediti disponibili. Se l'accesso al prova è esaurito, richiedere la connessione per utilizzare il saldo del tuo account. |
| 429 / APIError | Ispezionare error.retry_after e ridurre il tasso di richiesta. La SDK invia ogni richiesta una volta e non si riprova automaticamente. |
| SubmissionUnknownError | Una presentazione timed-out può già essere accettata. Controllare History prima di ripeterlo; riutilizzare un lavoro salvato ID quando disponibile. |
| asyncio.run() / running event loop | L'uso attende il main() in un notebook o in un loop di eventi esistente. Tenere asyncio.run(main())) per uno script standalone. |

- [Richiedi la cronologia](https://flashdata.dev/app/jobs)
- [Billing](https://flashdata.dev/app/billing)
- [Errori e ripristino Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/errors.md)
