# Formats de réponse

Choisissez du JSON structuré pour votre application ou du contenu Markdown pour un agent IA. Deux en-têtes contrôlent la réponse.

Référence canonique : https://flashdata.dev/fr/docs/guides/response-formats
Vérifié le 2026-11-04 par FlashData

<a id="headers"></a>

## Choisir un format

Par défaut, la réponse est en JSON avec les champs de résultat d’origine. Accept sélectionne JSON ou le texte brut ; X-Respond-With: markdown convertit le contenu des résultats en Markdown. Le corps de la requête reste en JSON.

| Réponse | Accept | X-Respond-With | Usage |
| --- | --- | --- | --- |
| JSON | application/json | Omettre | Lire les champs dans le code · par défaut |
| JSON + Markdown | application/json | markdown | Fournir du contexte à un agent avec des métadonnées structurées |
| Texte brut | text/plain | Omettre | Lire les champs d’origine dans un terminal |
| Texte + Markdown | text/plain | markdown | Lire les métadonnées et le Markdown ensemble |


<a id="examples"></a>

## Exemples de requêtes et de réponses

Ces onglets montrent la même recherche Google dans chaque format. Utilisez Bash et cURL 7.76+, avec FLASHDATA_API_KEY défini sur une clé autorisant google_search. Chaque commande exécutée soumet une recherche facturable.

### JSON

Format par défaut. Analysez le tableau results ; ses champs dépendent de la source.

#### Requête · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### Exemple de réponse · valeurs illustratives

```json
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Example page",
          "link": "https://example.com/article",
          "snippet": "A short source snippet."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-10-22T12:00:00.000Z"
}
```


### JSON + Markdown

Lisez content comme une chaîne Markdown. Ce champ remplace results ; source, status et usage restent disponibles comme champs JSON.

#### Requête · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'X-Respond-With: markdown' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### Exemple de réponse · valeurs illustratives

```json
{
  "source": "google_search",
  "status": "done",
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-10-22T12:00:00.000Z",
  "content": "# Google search\n\n## Organic\n\n### 1. Example page\n\n**Link:** <https://example.com/article>\n\n**Snippet:** A short source snippet\\.\n"
}
```


### Texte brut

Lisez la réponse comme du texte. Elle présente les champs d’origine avec une indentation ; ce n’est pas un document JSON.

#### Requête · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/plain' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### Exemple de réponse · valeurs illustratives

```text
Source: "google_search"
Status: "done"
Results:
  1:
    Organic:
      1:
        Title: "Example page"
        Link: "https://example.com/article"
        Snippet: "A short source snippet."
Usage:
  Credits: 0.01
Created at: "2026-10-22T12:00:00.000Z"
```


### Texte + Markdown

Lisez la réponse comme du texte : les métadonnées d’abord, puis le contenu Markdown.

#### Requête · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: text/plain' \
  --header 'X-Respond-With: markdown' \
  --data '{"source":"google_search","query":"vector databases"}'
```

#### Exemple de réponse · valeurs illustratives

```text
Source: "google_search"
Status: "done"
Usage: {"credits":0.01}
Created at: "2026-10-22T12:00:00.000Z"

Markdown Content:
# Google search

## Organic

### 1. Example page

**Link:** <https://example.com/article>

**Snippet:** A short source snippet\.
```


- [Authentification API](https://flashdata.dev/fr/docs/guides/headers-and-authentication/reference.md)
- [Champs de réponse Google Search](https://flashdata.dev/fr/docs/sources/google_search/reference.md#response)

<a id="supported-endpoints"></a>

## Points d’accès compatibles

Les mêmes règles s’appliquent aux sources de requête Google Search et YouTube. Pour YouTube Download, elles formatent le relevé de livraison, pas les octets vidéo ou audio. Les API du compte, les manifestes et parties NDJSON Bulk, les callbacks et les réponses MCP utilisent leurs propres formats.

| Point d’accès | JSON / texte brut | Contenu Markdown |
| --- | --- | --- |
| POST /v1/queries/realtime | Pris en charge | Pris en charge |
| GET /v2/jobs/{id}/results | Pris en charge | Pris en charge |
| POST /v1/queries | Reçu de soumission | Ignoré — à sélectionner lors de la lecture des résultats |
| POST /v1/queries/batch | Reçu de soumission | Ignoré — à sélectionner lors de la lecture des résultats |
| GET /v2/jobs/{id} | État de la tâche | Ignoré — aucun contenu de résultat ici |


<a id="completed-results"></a>

## Formater le résultat d’une tâche terminée

Définissez les en-têtes lors de la lecture du résultat, même si vous les aviez définis à la soumission. Définissez JOB_ID avec l’identifiant d’une tâche terminée à laquelle vous avez accès. Ce GET lit les résultats existants sans soumettre de nouvelle requête.

| Format demandé | Réponse des résultats |
| --- | --- |
| JSON d’origine | 302 avec une URL de stockage signée dans Location. Récupérez cette URL séparément, sans X-API-Key. Les résultats stockés peuvent être compressés avec gzip. |
| Texte brut ou l’une des options Markdown | 200 avec le corps formaté directement dans la réponse. |

### Récupérer du Markdown dans du JSON · cURL / Bash

```bash
curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}/results" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json' \
  --header 'X-Respond-With: markdown'
```

- [Récupérer le JSON d’origine · Python et cURL](https://flashdata.dev/fr/docs/reference/realtime-and-async/reference.md#results)

<a id="errors-and-scope"></a>

## Erreurs de format

Les erreurs API restent en JSON ou application/problem+json, même si vous demandez du texte brut. Vérifiez le statut HTTP avant d’analyser le format prévu en cas de réussite.

| Statut / code | Correction |
| --- | --- |
| 400 · unsupported_representation | Utilisez X-Respond-With: markdown ou omettez cet en-tête. Les valeurs comme json ou text ne sont pas prises en charge. |
| 406 · not_acceptable | Utilisez Accept: application/json ou text/plain. text/markdown et application/xml ne sont pas pris en charge. |

- [Erreurs et codes d’état](https://flashdata.dev/fr/docs/errors/reference.md)

<a id="negotiation"></a>

## Détails de l’en-tête Accept

Omettez Accept ou envoyez */* pour obtenir du JSON. Les réponses utilisent UTF-8. Les plages de types de média et les pondérations q sont prises en charge ; un charset non pris en charge renvoie 406, sauf si une autre plage acceptable correspond. Content-Type: application/json décrit le corps de la requête, pas la réponse.

### Préférer le texte, accepter le JSON

```http
Accept: text/plain; charset=utf-8, application/json;q=0.8
```

