taskType selecciona el motor. Todas las tareas se envían igual y todos los resultados vuelven en el mismo objeto de resultado. Solo cambia de un motor a otro el objeto response que contiene.
Lo que comparten todas las tareas
GET /v1/async/task/{id} devuelve el mismo objeto de resultado para todos los motores: success, task (id, estado y metadatos), credits y, cuando la tarea termina, response o error. Consulta Tareas asíncronas para el ciclo de vida y Webhooks para la entrega push.
Todos los motores de respuesta ponen la respuesta en response.text y las páginas que citó en response.sources, un array de { position, url, label } más campos propios de cada motor. Google AI Overviews es la excepción: el resumen está en response.aioverview, dentro de un objeto de resultados de búsqueda.
Motores de respuesta
SERP
WEB_SCRAPE: url es obligatorio: una página o PDF públicos, hasta 2.048 caracteres. render la lee en un navegador tras ejecutar su script, y maxAge acepta una lectura en caché de hasta siete días.
COMMERCE_SERP: site obligatorio: amazon, walmart, target, ebay, aliexpress, google_shopping, sephora o ulta (US), coupang, oliveyoung, 11st, lotteon, musinsa o kurly (KR), rakuten, yahoo_shopping o qoo10 (JP), flipkart, myntra o nykaa (IN), o zalando (DE). query: obligatorio, de 1 a 500 caracteres. country: opcional, por defecto el país de la tienda. limit: entero opcional de 1 a 40, con 20 por defecto.
COMMERCE_PRODUCT: url obligatorio: una página de producto de amazon, walmart, target, sephora o ulta (US), 11st, lotteon, musinsa, kurly o oliveyoung (KR), rakuten, yahoo_shopping o qoo10 (JP), flipkart, myntra o nykaa (IN), o zalando (DE), de hasta 2.048 caracteres. country: opcional, por defecto el país de la tienda.
Search
WEB_SCRAPE: url es obligatorio: una página o PDF públicos, hasta 2.048 caracteres. render la lee en un navegador tras ejecutar su script, y maxAge acepta una lectura en caché de hasta siete días.
Search y Pro Search se ejecutan en su propio endpoint, POST /v1/search, y devuelven los resultados en la misma respuesta: 0.5 créditos por búsqueda y 2 por búsqueda pro.
Los precios son por tarea completada. Créditos y límites explica las reservas, los cobros y los complementos.
Qué campo del payload se lee
Para los motores enumerados a continuación, la validación acepta una tarea que lleveprompt o query, de 1 a 100.000 caracteres (400 VALIDATION_ERROR en otro caso). Cada motor lee primero un campo y recurre al otro, así que una solicitud enviada con la otra clave igualmente se ejecuta:
CHATGPT,GEMINI,PERPLEXITY,COPILOT,BING_AIMODE,META_AI,QWEN,DOUBAO,BAIDU_WENXINyBING_SEARCHleenprompty despuésquery.GOOGLE_AIO,GOOGLE_AIMODE,GOOGLE_SERP,GOOGLE_PLACES,GOOGLE_NEWS,NAVER_AI_BRIEF,NAVER_AI_TAB,NAVER_SERPyBAIDU_AI_SEARCHleenqueryy despuésprompt.BRAVE_SEARCHleequeryy, si falta,prompt.
Alias aceptados
Estos nombres se aceptan al enviar y se ejecutan como el taskType canónico. El código nuevo debe enviar el nombre canónico.GOOGLE y AIMODE son los nombres anteriores de GOOGLE_AIO y GOOGLE_AIMODE. Una tarea responde con el nombre con el que se envió, y el uso, los monitores y los informes muestran los dos motores como GOOGLE y AIMODE.
Los motores privados se rechazan con
403 ENGINE_PRIVATE.
La lista en vivo
GET /v1/capabilities no necesita clave de API y devuelve cada taskType público con sus alias, endpoint, créditos, campos de entrada obligatorios y opcionales, si acepta state e include.html, su política de países y un payload de ejemplo mínimo. Se genera a partir del mismo código que aplica cada regla, así que úsalo para alimentar los selectores de motor y de país.
Opciones de la solicitud
- Respuestas en Markdown y en bruto: qué flags
includerespeta cada motor. - Análisis de la respuesta: marcas, recomendaciones, sentimiento y tipos de fuente junto a la respuesta.
- Páginas HTML: la pantalla que mostró el motor, como una página que puedes compartir.
- Regiones y ubicación: países, ubicaciones del dispositivo y capacidad.