> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrer une intégration existante

> Changez deux constantes. Lisez ensuite les points où le comportement diffère.

Cette API implémente le contrat standard de tâches asynchrones. Pour les endpoints qu'elle prend en charge, les
schémas de requête et de réponse sont inchangés : un client qui fonctionne n'a généralement besoin d'aucune modification de code.

## La migration

```diff theme={null}
- const BASE = "https://api.your-current-provider.example"
+ const BASE = "https://api.querying.ai"
```

Faites pointer votre constante de clé d'API vers une clé querying.ai. Votre URL de webhook, vos clés d'idempotence,
vos types de tâche et votre analyse des réponses restent tels quels.

## Ce qui est implémenté

<CardGroup cols={2}>
  <Card title="Pris en charge" icon="check">
    `POST /v1/async/task`

    `POST /v1/async/task/batch`

    `GET /v1/async/task/{id}`

    Callbacks webhook
  </Card>

  <Card title="Non implémenté" icon="x">
    Endpoints synchrones `/v1/monitor/*`

    `/v1/async/status`
  </Card>
</CardGroup>

La famille synchrone `/v1/monitor/*` est absente à dessein. Chaque moteur fonctionne ici de manière asynchrone ; une
requête qui bloque le temps d'une interrogation n'est pas une forme que propose ce service.

## Où le comportement diffère

<AccordionGroup>
  <Accordion title="1. Pas de limiteur de débit : utilisez les lots" icon="gauge">
    Il n'y a pas de limite de débit par clé. Pour de gros volumes, utilisez la soumission par lot afin de réduire les allers-retours.

    Consultez [Régions et bonnes pratiques](/fr/engines/capacity).
  </Accordion>

  <Accordion title="2. Les crédits dépendent du moteur" icon="coins">
    `credits` est présent dans chaque réponse, dans l'enveloppe. Les réponses de soumission et de polling indiquent
    `{ "creditsToCharge": 0, "creditsCharged": 0 }` ; les webhooks indiquent le coût en crédits du moteur (1 à 3 crédits selon le moteur).

    Les tâches échouées ne sont pas facturées. Les soldes de crédits sont visibles dans le tableau de bord.
  </Accordion>

  <Accordion title="3. Certaines paires moteur × région sont refusées d'emblée" icon="ban">
    Une combinaison ne peut pas être servie du tout : `CHATGPT`/`PERPLEXITY`/`GEMINI` vers `CN`, où aucune sortie n'est
    disponible et où la requête n'atteint jamais la cible. Elle échoue immédiatement avec `422 REGION_UNSUPPORTED` au lieu
    d'être acceptée. `422 REGION_UNAVAILABLE` couvre la version transitoire du même cas.

    Un client qui suppose que toute soumission bien formée est acceptée a besoin d'une branche ici. Consultez [Régions](/fr/engines/capacity).
  </Accordion>

  <Accordion title="4. Les flags include sont presque sans effet" icon="toggle-left">
    Les flags `payload.include` sont acceptés, mais la plupart des moteurs renvoient une réponse de forme fixe et les
    ignorent. Seul ChatGPT respecte l'ensemble complet ; `GEMINI` ne respecte que `markdown` et `rawResponse`.

    Demander `html` à Gemini, par exemple, est ignoré silencieusement : ni erreur, ni champ. Consultez le
    [tableau de prise en charge des flags](/fr/engines/overview).
  </Accordion>

  <Accordion title="5. Un code de statut supplémentaire : 422" icon="hash">
    La gestion des erreurs est par ailleurs classique : les échecs de validation renvoient `400`, `401` signale
    `MISSING_API_KEY`, `404` signale `RESOURCE_NOT_FOUND`, et `details` nomme le champ fautif.

    Le seul ajout est la paire `422` (`REGION_UNSUPPORTED`, `REGION_UNAVAILABLE`) décrite plus haut. Nous vous prévenons
    d'emblée quand une région ne peut pas être servie : un client qui n'a jamais eu à gérer de `422` commencera à en voir.
  </Accordion>

  <Accordion title="6. Une tâche échouée ajoute une chaîne `error` de premier niveau" icon="triangle-alert">
    `GET /v1/async/task/{id}` sur une tâche `FAILED` renvoie un champ `error` de premier niveau que le schéma du statut de
    tâche ne définit pas par ailleurs, et c'est une **simple chaîne**, pas l'objet `{code, message, timestamp}` des erreurs de requête.

    ```json theme={null}
    { "success": true, "task": { "status": "FAILED", "...": "..." }, "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline." }
    ```

    Un client qui traite un `body.error` non vide comme une *requête* échouée interprétera mal une *tâche* échouée récupérée
    avec succès. Branchez plutôt sur `task.status`.
  </Accordion>
</AccordionGroup>

<Note>
  Ces comportements ont été établis en appelant cette API, pas en lisant un schéma. Si une spécification publiée et une
  réponse réelle divergent, ces pages documentent la réponse réelle.
</Note>

## Choisir le bon `taskType`

Si votre intégration actuelle appelle un endpoint par moteur, le nom du moteur correspond à un `taskType` :

| Vous appeliez | `taskType` |
| - | - |
| ChatGPT | `CHATGPT` |
| Perplexity | `PERPLEXITY` |
| Gemini | `GEMINI` |
| Google AI Mode | `AIMODE` |
| Google AI Overview | `GOOGLE` |
| Naver | `NAVER_AI_BRIEF` / `NAVER_AI_TAB` |

<Note>
  Que `GOOGLE` désigne « AI Overview » est une convention de nommage, pas un nom de produit Google. La réponse est une
  enveloppe SERP dont `aioverview` est un membre nullable : consultez [la forme GOOGLE](/fr/engines/overview).
</Note>

## Vérifier la bascule

Faites tourner en parallèle votre intégration actuelle et celle-ci pendant un temps, et comparez les champs que vous
consommez réellement, en pratique `response.text`, `response.sources[]` et `response.markdown`. Une comparaison en
miroir détecte les écarts de forme qu'une vérification de schéma ne voit pas, comme une liste de sources remplie mais
ordonnée différemment.