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.
Search
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 tragaprompt 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_WENXINeBING_SEARCHleemprompte depoisquery.GOOGLE_AIO,GOOGLE_AIMODE,GOOGLE_SERP,GOOGLE_PLACES,GOOGLE_NEWS,NAVER_AI_BRIEF,NAVER_AI_TAB,NAVER_SERPeBAIDU_AI_SEARCHleemquerye depoisprompt.BRAVE_SEARCHlêquerye, se faltar,prompt.
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.
Opções da requisição
- Markdown e respostas brutas: quais flags
includecada mecanismo respeita. - Análise da resposta: marcas, recomendações, sentimento e tipos de fonte junto com a resposta.
- Páginas HTML: a tela que o mecanismo mostrou, como uma página compartilhável.
- Regiões e localização: países, localizações de dispositivo e capacidade.