Saltar para o conteúdo principal
taskType seleciona o mecanismo. Você envia toda tarefa do mesmo jeito, e todo resultado volta no mesmo objeto de resultado. Só o objeto response dentro dele muda de um mecanismo para outro.

O que toda tarefa tem em comum

GET /v1/async/task/{id} retorna o mesmo objeto de resultado para todo mecanismo: success, task (id, status e metadados), credits e, quando a tarefa termina, response ou error. Veja Tarefas assíncronas para o ciclo de vida e Webhooks para a entrega por push. Todo mecanismo de resposta coloca a resposta em response.text e as páginas citadas em response.sources, um array de { position, url, label } mais campos específicos do mecanismo. Google AI Overviews é a exceção: a visão geral fica em response.aioverview, dentro de um objeto de resultados de busca.

Mecanismos de resposta

SERP

WEB_SCRAPE: url é obrigatório: uma página ou PDF públicos, até 2.048 caracteres. render lê a página em um navegador após o script rodar, e maxAge aceita uma leitura em cache de até sete dias. COMMERCE_SERP: site obrigatório: amazon, walmart, target, ebay, aliexpress, google_shopping, sephora ou ulta (US), coupang, oliveyoung, 11st, lotteon, musinsa ou kurly (KR), rakuten, yahoo_shopping ou qoo10 (JP), flipkart, myntra ou nykaa (IN), ou zalando (DE). query: obrigatório, de 1 a 500 caracteres. country: opcional, por padrão o país da loja. limit: inteiro opcional de 1 a 40, com padrão 20. COMMERCE_PRODUCT: url obrigatório: uma página de produto de amazon, walmart, target, sephora ou ulta (US), 11st, lotteon, musinsa, kurly ou oliveyoung (KR), rakuten, yahoo_shopping ou qoo10 (JP), flipkart, myntra ou nykaa (IN), ou zalando (DE), com até 2.048 caracteres. country: opcional, por padrão o país da loja. WEB_SCRAPE: url é obrigatório: uma página ou PDF públicos, até 2.048 caracteres. render lê a página em um navegador após o script rodar, e maxAge aceita uma leitura em cache de até sete dias. Search e Pro Search rodam em um endpoint próprio, POST /v1/search, e devolvem os resultados na mesma resposta: 0.5 crédito por busca e 2 por busca pro. Os preços são por tarefa concluída. Créditos e limites explica reservas, cobranças e complementos.

Qual campo do payload é lido

Para os mecanismos listados abaixo, a validação aceita uma tarefa que traga prompt ou query, de 1 a 100.000 caracteres (caso contrário, 400 VALIDATION_ERROR). Cada mecanismo lê um campo primeiro e recorre ao outro, então uma requisição enviada com a outra chave ainda é executada:
  • CHATGPT, GEMINI, PERPLEXITY, COPILOT, BING_AIMODE, META_AI, QWEN, DOUBAO, BAIDU_WENXIN e BING_SEARCH leem prompt e depois query.
  • GOOGLE_AIO, GOOGLE_AIMODE, GOOGLE_SERP, GOOGLE_PLACES, GOOGLE_NEWS, NAVER_AI_BRIEF, NAVER_AI_TAB, NAVER_SERP e BAIDU_AI_SEARCH leem query e depois prompt.
  • BRAVE_SEARCH lê query e, se faltar, prompt.
Se você enviar os dois, vale o campo lido primeiro. A coluna Lê mostra o campo que a página de cada mecanismo documenta.

Aliases aceitos

Estes nomes são aceitos no envio e executados como o taskType canônico. Em código novo, envie o nome canônico. GOOGLE e AIMODE são os nomes anteriores de GOOGLE_AIO e GOOGLE_AIMODE. Uma tarefa responde com o nome com que foi enviada, e o uso, os monitores e os relatórios mostram os dois motores como GOOGLE e AIMODE. Mecanismos privados são recusados com 403 ENGINE_PRIVATE.

A lista ao vivo

GET /v1/capabilities não exige chave de API e retorna todo taskType público com seus aliases, endpoint, créditos, campos de entrada obrigatórios e opcionais, se aceita state e include.html, sua política de países e um payload de exemplo mínimo. Ele é gerado pelo mesmo código que aplica cada regra, então use-o para alimentar seletores de mecanismo e de país.
Veja a referência da API para o schema da resposta.

Opções da requisição