# Python SDK Quickstart

Instale o Python SDK e imprima resultados de busca com algumas linhas de código. Inclui exemplos síncronos e assincios.

Referência canônica: https://flashdata.dev/pt/docs/guides/flashdata-python
2026-11-04 por FlashData

- [GitHub](https://github.com/flashdatadev/flashdata-python) — Fonte e referência SDK
- [Obtenha uma chave de API](https://flashdata.dev/app/api-keys) — Crie uma chave no console

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

## Faça seu primeiro pedido Python

Instale o SDK, defina sua chave API e execute uma busca. As respostas são dicionários Python por padrão.

- [Python SDK referência](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>

### Instale o SDK

Requer Python 3.10+. Execute esses comandos no diretório do seu projeto. Já está usando um ambiente virtual? Instale os dados flash==1.1.0 com o python do ambiente -m pip em vez disso.

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


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

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

### Autenticação

Crie uma chave API com permissão Google Search, ou reutilize uma chave autorizada. Coloque-o neste terminal usando o prompt escondido abaixo.

Pule o prompt se FLASHDATA_API_KEY já está definido. Estes exemplos lêem a variável diretamente, eles não carregam arquivos env.

#### Bash

##### Chave escondida pronta. 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

##### Chave escondida pronta. 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
```


- [Criar conta](https://flashdata.dev/signup)
- [Abrir API Keys](https://flashdata.dev/app/api-keys)
- [Abra Billing](https://flashdata.dev/app/billing)
- [Armação do teste do agente](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md)

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

### Faça uma pesquisa

Guarde isso como quickstart.py, então execute com o mesmo ambiente virtual. Faz um pedido Google Search para até cinco resultados e imprime títulos, URLs e créditos usados.

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

##### Executar

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


#### Windows PowerShell

##### Executar

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



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

### Confira o resultado

O script sai normalmente depois de verificar o status. Espero títulos de origem e URLs seguido de créditos usados. Uma lista orgânica vazia é uma resposta válida, os resultados variam com sua consulta.

| Campo | Use |
| --- | --- |
| results[].organic[] | Google Search: título, link e trecho. Outras fontes têm diferentes campos de resultados. |
| usage.credits | Custo deste pedido. Até cinco resultados aqui são um pedido de busca. |

#### Exemplo de saída

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


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

## Tente outra fonte de dados

Cada guia é um roteiro completo. Substitua quickstart.py por um exemplo e execute com o comando do passo 3. Cada corrida envia um novo pedido, a chave precisa da permissão da fonte mostrada.

### Google Notícias

Requer google_news. Imprime títulos de artigos e links de origem do 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"))
```


### YouTube metadados

Requer youtube_metadata. Imprime o título do vídeo, canal e duração em segundos. Substitua o vídeo ID por um que queira inspecionar.

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


### YouTube transcrição

Requer youtube_transcript. Imprime uma transcrição automática inglesa existente de results[].fullText. O vídeo deve ter essa faixa, essa chamada não gera nem traduz legendas.

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


- [Todos os métodos e parâmetros de origem](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/sources/index.md)

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

## O que o Python SDK suporta

| Use | SDK pontos de entrada |
| --- | --- |
| google / youtube | Google Search, Notícias, Imagens, Compras, Vídeos e Locais; Descoberta YouTube, metadados, legendas, transcrições e dados do canal. |
| youtube.download | Envie um trabalho de entrega de áudio ou vídeo para o seu armazenamento na nuvem. Requer permissão youtube_download e configuração de armazenamento; siga o exemplo completo de download abaixo. |
| jobs / bulk | Salve o trabalho aceito ID, espere pela conclusão e recupere os resultados. Use o volume para maiores conjuntos de dados de vídeo ID e retome trabalhos existentes após uma reinicialização. |
| account | Leia acesso, equilíbrio, preços, limites e uso antes do trabalho recorrente. Reutilize uma chave autorizada do seu ambiente ou loja secreta. |
| respond_with / accept | Use respond_with="markdown" para Markdown em resposta."content"# Ou aceitar #"text/plain" Por uma corda. Dicionários JSON são o padrão. |

- [Exemplo completo de download do Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/examples/youtube_download.py)
- [Configure o armazenamento de download](https://flashdata.dev/pt/docs/guides/youtube-download-guide/reference.md)
- [Formatos de resposta Python](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/response-formats.md)

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

## Use assíncio

Substitua quickstart.py por esta versão e use o mesmo comando de execução. AsyncFlashData expõe os mesmos recursos com espera. Isso ainda espera por uma resposta de busca em tempo real, mode="async" envia uma tarefa de background do lado do servidor.

Em Jupyter ou uma aplicação com um loop de eventos em execução, use waiting main() em vez de asyncio.run(main()). Reutilize o cliente dentro do loop do evento.

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

- [Configuração do cliente Async](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/client.md)

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

## Próximos passos

- [verificações de contas e resultados salvos](https://flashdata.dev/pt/docs/guides/sdk-operations/reference.md)
- [Trabalhos de fundo e lote](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/jobs.md)
- [Conjuntos de dados Bulk](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/bulk.md)
- [Referência do método SDK](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/api-reference.md)

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

## Se um passo falhar

| Problema | Consertar |
| --- | --- |
| ModuleNotFoundError | Instale e execute com o mesmo intérprete: .venv/bin/python -m pip mostrar flashdata (Windows:.\.venv\Scripts\python.exe -m pip mostrar flashdata). Não nomeie seu script flashdata.py. |
| KeyError: FLASHDATA_API_KEY / 401 | Defina uma chave API ativa no mesmo terminal. Um arquivo Env sozinho não é carregado por este exemplo. Use uma chave API, não um símbolo MCP OAuth. |
| 403 | Conceda a permissão de origem exigida pelo exemplo para esta chave. |
| 402 | Verifique Billing para os créditos disponíveis. Se o acesso ao teste estiver esgotado, reclame a conexão para usar o saldo da conta. |
| 429 / APIError | Inspecione error.retry_after e reduza a taxa de solicitação. O SDK envia cada pedido uma vez e não tenta novamente automaticamente. |
| SubmissionUnknownError | Uma submissão cronometrada já pode ser aceita. Verifique History antes de repeti-lo, reutilize um trabalho salvo ID quando disponível. |
| asyncio.run() / running event loop | Use o main() em um notebook ou loop de eventos existentes. Mantenha asyncio.run(main()) para um script autônomo. |

- [Requisito histórico](https://flashdata.dev/app/jobs)
- [Billing](https://flashdata.dev/app/billing)
- [Erros Python e recuperação](https://github.com/flashdatadev/flashdata-python/blob/v1.1.0/docs/errors.md)
