API do Coletor Gemini: Capture Respostas do Google Gemini como Dados

TL;DR:

• O Scraper Gemini captura a resposta do Google Gemini como dados estruturados. Envie um prompt para scraper.gemini; receba o texto da resposta mais as citações nas quais o Gemini se baseou.
• É um fluxo assíncrono de duas chamadas. POST o prompt para criar uma tarefa, depois GET o resultado pelo task_id — em uma execução ao vivo, a resposta retornou em cerca de 12 segundos.
• As citações vêm estruturadas, não raspadas de HTML. Cada uma contém título, url, nome_do_site, trecho, favicon e os trechos destacados que o Gemini usou.
• Localize com um código de país. O campo country molda a resposta para uma região, da mesma forma que um usuário lá veria.
• É assim que você monitora a visibilidade da marca em respostas de IA. Pergunte ao Gemini as perguntas que seus clientes fazem e leia quais fontes ele cita.
• Gratuito para começar. Novas contas do Scrapeless incluem uso gratuito da API Scraper — inscreva-se em app.scrapeless.com.

Introdução: leia o que o Gemini realmente responde

Os motores de resposta de IA agora ficam entre os usuários e a web aberta. Quando alguém pergunta ao Google Gemini sobre "o melhor serviço de proxy" ou "coisas para fazer em Nova York", a resposta — e as fontes que cita — moldam o que esse usuário acredita antes de clicar em qualquer coisa. Para monitoramento de marca, pesquisa competitiva e otimização de motores de resposta, a pergunta já não é "onde estou classificado no Google", mas "o que o Gemini diz e quem ele cita".

O Scraper Gemini do Scrapeless responde a isso programaticamente. Você envia um prompt para o ator scraper.gemini e recebe o texto da resposta mais as citações estruturadas por trás disso. Este guia cobre a forma do pedido, um primeiro curl, o esquema de resposta, uma integração em Python e como usá-lo — cada pedido e resposta abaixo foi capturado em relação à API ao vivo.

O que você pode fazer com isso

• Capturar o texto da resposta do Gemini — a resposta completa como Markdown estilo CommonMark, pronta para armazenar ou analisar.
• Ler as citações — as fontes que o Gemini se baseou para a resposta, cada uma com título, URL e o trecho utilizado.
• Rastrear menções à marca em respostas de IA — pergunte as perguntas que seus compradores fazem e veja se você aparece.
• Localizar por região — defina country para ver a resposta como um usuário naquele mercado veria.
• Alimentar um pipeline de monitoramento — execute os mesmos prompts em uma agenda e compare as fontes ao longo do tempo.

Por que o Scraper Gemini do Scrapeless

O Scraper Gemini é parte da linha de Scrapers de Chat LLM do Scrapeless, a forma gerenciada de ler respostas de motores de IA como dados. Para o Gemini especificamente, ele traz:

• Um único contrato de solicitação — envie um prompt, obtenha a resposta e suas citações; sem navegador para dirigir.
• Citações estruturadas — as fontes retornam como campos, não marcado que você precisa analisar.
• Proxies residenciais em mais de 195 países — as respostas são buscadas através de uma saída limpa, apropriada para a região.
• Localização por país — um campo molda a resposta para um mercado.

Obtenha sua chave da API no plano gratuito em app.scrapeless.com.

Pré-requisitos

• Uma conta do Scrapeless e chave da API — inscreva-se em app.scrapeless.com
• curl para o primeiro pedido e Python 3.10+ para a integração
• Familiaridade básica com HTTP e JSON

Como o Scraper Gemini funciona

O fluxo é de duas chamadas: crie uma tarefa, depois busque seu resultado.

Parâmetros da solicitação

A autenticação é o cabeçalho x-api-token em ambas as chamadas.

Captura rápida com curl

Crie a tarefa:

curl -X POST https://api.scrapeless.com/api/v2/scraper/request \
  -H "x-api-token: ${SCRAPELESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "scraper.gemini",
    "input": { "prompt": "Atrações recomendadas em Nova York", "country": "US" }
  }'
# { "status": "pending", "task_id": "3886db31-…" }

Em seguida, busque o resultado pelo task_id:

curl -X GET https://api.scrapeless.com/api/v2/scraper/result/{task_id} \
  -H "x-api-token: ${SCRAPELESS_API_KEY}"

Envelope de resposta

Uma vez que status é success, a resposta e as citações estão em task_result:

// amostra ilustrativa — o formato do campo é exato (capturado ao vivo); valores abreviados
{
  "status": "success",
  "task_result": {
    "prompt": "Atrações recomendadas em Nova York",
    "result_text": "Nova York é um belo caos de cultura, história…",
    "citations": [
      {
        "title": "20 Melhores Coisas para Fazer em NYC",
        "url": "https://example.com/nyc",
        "website_name": "Exemplo Viagem",
        "snippet": "Da Estátua da Liberdade a…",
        "favicon": "https://example.com/favicon.ico",
        "highlights": ["Estátua da Liberdade", "Central Park"]
      }
    ]
  }
}

}

Em uma execução ao vivo, isso retornou em cerca de 12 segundos com 15 citações, cada uma contendo os seis campos acima.

---

## Integrando a API em Python

Crie a tarefa, faça polling até que esteja concluída e leia a resposta:

```python
import os
import time
import requests

API_KEY = os.environ["SCRAPELESS_API_KEY"]
BASE = "https://api.scrapeless.com"
HEADERS = {"x-api-token": API_KEY, "Content-Type": "application/json"}


def ask_gemini(prompt: str, country: str = "US") -> dict:
    created = requests.post(
        f"{BASE}/api/v2/scraper/request",
        headers=HEADERS,
        json={"actor": "scraper.gemini", "input": {"prompt": prompt, "country": country}},
        timeout=60,
    )
    task_id = created.json()["task_id"]

    for _ in range(30):
        time.sleep(3)
        got = requests.get(f"{BASE}/api/v2/scraper/result/{task_id}", headers=HEADERS, timeout=60)
        data = got.json()
        if data.get("status") in ("success", "failed"):
            return data
    raise TimeoutError("resultado não pronto a tempo")


result = ask_gemini("Atrações recomendadas em Nova Iorque")
answer = result["task_result"]
print(answer["result_text"])
for c in answer["citations"]:
    print("-", c["website_name"], c["url"])

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

Como evitar problemas comuns

• Um campo que não está presente é nulo, não um erro. Nem toda resposta contém highlights ou um favicon; trate cada campo de citação como opcional e proteja sua ausência.
• Recupere os resultados prontamente. O resultado é recuperado pelo task_id; faça polling logo após criar a tarefa, em vez de muito depois, e prefira um intervalo de polling curto a ler muito mais tarde.
• Prenda o país ao mercado que você está estudando. O campo country altera a resposta; mantenha-o fixo por execução de monitoramento para que os resultados sejam comparáveis ao longo do tempo.
• As respostas variam entre as execuções. A formulação do Gemini muda de execução para execução, então compare as fontes de citação ao longo do tempo, não a prosa exata — a maneira como os motores de resposta exibem páginas é descrita em as próprias diretrizes de recursos de IA do Google para a web, e o contrato HTTP que você está chamando segue especificação de semântica HTTP.

Conclusão: sua marca, como o Gemini a vê

O Gemini Scraper transforma uma resposta de IA em dados que você pode rastrear: o texto da resposta e as fontes exatas por trás dela, em um fluxo de duas chamadas. Execute os prompts que seus clientes pedem, armazene as citações e observe como sua visibilidade nas respostas do Gemini muda ao longo do tempo. Combine isso com os outros motores na linha Universal Scraping API, leia sobre por que os motores de resposta mudaram a busca, e a documentação cobre cada campo.

Pronto para Construir Seu Pipeline de Dados Acelerado por IA?

Junte-se à nossa comunidade para reivindicar um plano gratuito e se conectar com desenvolvedores que monitoram respostas de IA: Discord · Telegram.

Inscreva-se em app.scrapeless.com para uso gratuito da API Scraper e veja preços para escala.

FAQ

P: O que o Gemini Scraper retorna?
O texto da resposta em Markdown (result_text) mais um array de citations — cada citação tem title, url, website_name, snippet, favicon, e os highlights que o Gemini usou. Em uma execução ao vivo, um prompt retornou 15 citações.

P: É síncrono?
Não. Você POSTa o prompt para criar uma tarefa e GETa o resultado pelo task_id. Em uma execução ao vivo, a resposta estava pronta em cerca de 12 segundos.

P: Posso localizar a resposta?
Sim — defina input.country para um código ISO. A resposta é moldada para aquele mercado, então mantenha-a fixa ao comparar resultados ao longo do tempo.

P: Por que as respostas mudam entre as execuções?
Respostas generativas variam em formulação de execução para execução. Para monitoramento, rastreie as fontes de citação e se sua marca aparece, não a prosa exata.

P: Preciso de um proxy?
Não. A saída é tratada internamente pelo ator através de IPs residenciais; você só envia o prompt e o país.