# Inicio rápido del SDK para Python

Instala el SDK para Python y muestra resultados de búsqueda con unas pocas líneas de código. Incluye ejemplos síncronos y con asyncio.

Referencia canónica: https://flashdata.dev/es/docs/guides/flashdata-python
Revisado: 2026-11-04 por FlashData

- [GitHub](https://github.com/flashdatadev/flashdata-python) — Código fuente y referencia del SDK
- [Obtén una clave API](https://flashdata.dev/app/api-keys) — Crea una clave en la consola

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

## Haz tu primera solicitud con Python

Instala el SDK, configura tu clave API y haz una búsqueda. Por defecto, las respuestas son diccionarios de Python.

- [Referencia del SDK para Python](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>

### Instala el SDK

Requiere Python 3.10+. Ejecuta estos comandos en el directorio de tu proyecto. Si ya usas un entorno virtual, instala flashdata==1.1.0 con su python -m pip y usa ese mismo intérprete en el paso 3.

#### Linux / macOS

##### Instalar

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


#### Windows PowerShell

##### Instalar

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


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

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

### Configura la autenticación

Crea una clave API con permiso para Google Search o reutiliza una clave autorizada. Ejecuta el bloque y pega la clave cuando se solicite; no se mostrará en pantalla.

Omite este paso si FLASHDATA_API_KEY ya está definida. Los ejemplos leen esa variable directamente; no cargan archivos .env.

#### Bash

##### Clave API · 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

##### Clave API · 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
```


- [Crear cuenta](https://flashdata.dev/signup)
- [Abrir API Keys](https://flashdata.dev/app/api-keys)
- [Abrir Billing](https://flashdata.dev/app/billing)
- [Configurar una prueba para agentes](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md)

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

### Haz una búsqueda

Guarda el código como quickstart.py en el directorio de tu proyecto. Ejecútalo con el Python del mismo entorno virtual y en la terminal donde configuraste la clave. Hace una solicitud de Google Search de hasta cinco resultados y muestra los títulos, las URLs y los créditos consumidos.

#### 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

##### Ejecutar

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


#### Windows PowerShell

##### Ejecutar

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



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

### Comprueba el resultado

El script comprueba que status sea done y termina sin errores. Verás los títulos y las URLs, seguidos de Credits used. Una lista organic vacía también es válida; los resultados dependen de tu búsqueda.

| Campo | Uso |
| --- | --- |
| results[].organic[] | Resultados de Google Search con los campos title, link y snippet. Otras fuentes devuelven campos distintos. |
| usage.credits | Créditos consumidos por la solicitud. Esta búsqueda de hasta cinco resultados cuenta como una sola solicitud. |

#### Ejemplo de respuesta

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


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

## Prueba otra fuente de datos

Cada pestaña contiene un script completo. Sustituye el contenido de quickstart.py por uno de estos ejemplos y usa el comando del paso 3 para ejecutarlo. Cada ejecución envía una nueva solicitud; la clave debe tener el permiso indicado.

### Google News

Requiere el permiso google_news. Muestra los títulos y enlaces de las noticias de 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"))
```


### Metadatos de YouTube

Requiere el permiso youtube_metadata. Muestra el título, el canal y la duración del vídeo en segundos. Sustituye el ID de ejemplo por el del vídeo que quieras consultar.

#### 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"))
```


### Transcripción de YouTube

Requiere el permiso youtube_transcript. Muestra una transcripción automática existente en inglés, obtenida de results[].fullText. El vídeo debe tener esa pista; esta llamada no genera ni traduce subtítulos.

#### 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", ""))
```


- [Métodos y parámetros de todas las fuentes](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/sources/index.md)

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

## Funciones del SDK para Python

| Uso | Métodos y servicios del SDK |
| --- | --- |
| google / youtube | Google Search, News, Images, Shopping, Videos y Places; búsqueda de vídeos, metadatos, subtítulos, transcripciones y datos de canales de YouTube. |
| youtube.download | Envía un trabajo para entregar audio o vídeo en tu almacenamiento en la nube. Requiere el permiso youtube_download y la configuración del almacenamiento. Consulta el ejemplo completo de descarga. |
| jobs / bulk | Guarda el ID del trabajo aceptado, espera a que termine y recupera los resultados. Usa bulk para procesar archivos grandes de IDs de vídeo y reanudar trabajos existentes tras un reinicio. |
| account | Consulta el acceso, el saldo, los precios, los límites y el uso antes de ejecutar tareas recurrentes. Reutiliza una clave autorizada de tu entorno o almacén de secretos. |
| respond_with / accept | Usa respond_with="markdown" para obtener Markdown en response["content"], o accept="text/plain" para obtener una cadena de texto. Por defecto, el JSON se devuelve como un diccionario. |

- [Ejemplo completo de descarga en Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/examples/youtube_download.py)
- [Configurar el almacenamiento para descargas](https://flashdata.dev/es/docs/guides/youtube-download-guide/reference.md)
- [Formatos de respuesta en Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/response-formats.md)

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

## Usa asyncio

Sustituye el contenido de quickstart.py por esta versión y usa el mismo comando para ejecutarla. AsyncFlashData ofrece los mismos recursos con await. La llamada sigue esperando una respuesta en tiempo real; mode="async" envía un trabajo en segundo plano al servidor.

En Jupyter o en una aplicación con un bucle de eventos activo, usa await main() en lugar de asyncio.run(main()). Reutiliza el cliente dentro de ese bucle de eventos.

### 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())
```

- [Configurar el cliente asíncrono](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/client.md)

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

## Siguientes pasos

- [Consultar la cuenta y reutilizar resultados](https://flashdata.dev/es/docs/guides/sdk-operations/reference.md)
- [Trabajos en segundo plano y solicitudes batch](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/jobs.md)
- [Procesamiento de datos con bulk](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/bulk.md)
- [Referencia de métodos del SDK](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/api-reference.md)

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

## Si un paso falla

| Problema | Qué hacer |
| --- | --- |
| ModuleNotFoundError | Instala y ejecuta con el mismo intérprete. Comprueba la instalación con .venv/bin/python -m pip show flashdata (Windows: .\.venv\Scripts\python.exe -m pip show flashdata). No llames flashdata.py a tu script. |
| KeyError: FLASHDATA_API_KEY / 401 | Define una clave API activa en la misma terminal. El ejemplo no carga archivos .env. Usa una clave API; los tokens OAuth de MCP no sirven para este ejemplo. |
| 403 | Pide al titular que conceda a esta clave el permiso de la fuente que requiere el ejemplo. |
| 402 | Consulta los créditos disponibles en Billing. Si la prueba se ha agotado, vincula la conexión a tu cuenta para usar su saldo. |
| 429 / APIError | Revisa error.retry_after y reduce la frecuencia de tus solicitudes. El SDK envía cada solicitud una vez, sin reintentos automáticos. |
| SubmissionUnknownError | La solicitud puede haberse aceptado aunque haya agotado el tiempo de espera. Revisa History antes de repetirla y reutiliza el ID del trabajo si lo guardaste. |
| asyncio.run() / running event loop | Usa await main() en un notebook o en un bucle de eventos activo. Mantén asyncio.run(main()) para ejecutar el script de forma independiente. |

- [Historial de solicitudes](https://flashdata.dev/app/jobs)
- [Facturación](https://flashdata.dev/app/billing)
- [Errores y recuperación en Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/errors.md)
