taskType sélectionne le moteur. Vous envoyez chaque tâche de la même façon, et chaque résultat revient dans le même objet de résultat. Seul l’objet response qu’il contient change d’un moteur à l’autre.
Ce que toutes les tâches partagent
GET /v1/async/task/{id} renvoie le même objet de résultat pour tous les moteurs : success, task (id, statut et métadonnées), credits et, une fois la tâche terminée, response ou error. Consultez Tâches asynchrones pour le cycle de vie et Webhooks pour la livraison push.
Chaque moteur de réponse place la réponse dans response.text et les pages qu’il cite dans response.sources, un tableau de { position, url, label } complété de champs propres au moteur. Google AI Overviews fait exception : l’aperçu se trouve sous response.aioverview, dans un objet de résultats de recherche.
Moteurs de réponse
SERP
WEB_SCRAPE : url est obligatoire : une page ou un PDF public, jusqu’à 2 048 caractères. render la lit dans un navigateur après exécution de ses scripts, et maxAge accepte une lecture en cache de sept jours au plus.
COMMERCE_SERP : site obligatoire : 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 : obligatoire, de 1 à 500 caractères. country : facultatif, par défaut le pays de la boutique. limit : entier facultatif de 1 à 40, avec 20 par défaut.
COMMERCE_PRODUCT : url obligatoire : une page produit 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), de 2 048 caractères au plus. country : facultatif, par défaut le pays de la boutique.
Search
WEB_SCRAPE : url est obligatoire : une page ou un PDF public, jusqu’à 2 048 caractères. render la lit dans un navigateur après exécution de ses scripts, et maxAge accepte une lecture en cache de sept jours au plus.
Search et Pro Search passent par leur propre endpoint, POST /v1/search, et renvoient les résultats dans la même réponse : 0.5 crédit par recherche, 2 par recherche pro.
Les prix s’entendent par tâche terminée. Crédits et limites explique les réservations, la facturation et les options.
Quel champ du payload est lu
Pour les moteurs listés ci-dessous, la validation accepte une tâche qui porteprompt ou query, de 1 à 100 000 caractères (400 VALIDATION_ERROR sinon). Chaque moteur lit un champ en premier et se rabat sur l’autre : une requête envoyée avec l’autre clé s’exécute donc quand même.
CHATGPT,GEMINI,PERPLEXITY,COPILOT,BING_AIMODE,META_AI,QWEN,DOUBAO,BAIDU_WENXINetBING_SEARCHlisentprompt, puisquery.GOOGLE_AIO,GOOGLE_AIMODE,GOOGLE_SERP,GOOGLE_PLACES,GOOGLE_NEWS,NAVER_AI_BRIEF,NAVER_AI_TAB,NAVER_SERPetBAIDU_AI_SEARCHlisentquery, puisprompt.BRAVE_SEARCHlitquery, puisprompt.
Alias acceptés
Ces noms sont acceptés à l’envoi et s’exécutent comme le taskType canonique. Le nouveau code doit envoyer le nom canonique.GOOGLE et AIMODE sont les anciens noms de GOOGLE_AIO et GOOGLE_AIMODE. Une tâche répond sous le nom avec lequel elle a été envoyée, et l’usage, les moniteurs et les rapports affichent les deux moteurs sous GOOGLE et AIMODE.
Les moteurs privés sont refusés avec
403 ENGINE_PRIVATE.
La liste en direct
GET /v1/capabilities ne demande pas de clé d’API et renvoie chaque taskType public avec ses alias, son endpoint, ses crédits, ses champs d’entrée obligatoires et facultatifs, s’il accepte state et include.html, sa règle de pays et un exemple de payload minimal. Elle est construite à partir du code même qui applique chaque règle : utilisez-la pour alimenter vos sélecteurs de moteur et de pays.
Options de requête
- Réponses Markdown et brutes : quels flags
includechaque moteur respecte. - Analyse de la réponse : marques, recommandations, sentiment et types de sources à côté de la réponse.
- Pages HTML : l’écran affiché par le moteur, sous forme de page partageable.
- Régions et localisation : pays, localisations d’appareil et capacité.