# Formati di risposta

Scegli il contenuto JSON strutturato per la tua applicazione o Markdown per un agente AI. Controllare la risposta con due intestazioni.

Riferimento canonico: https://flashdata.dev/it/docs/guides/response-formats
Recensito: 2026-11-04 da FlashData

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

## Scegli un formato

JSON con i campi di risultato originali è il default. Accept seleziona JSON o testo normale; X-Respond-With: markdown converte il contenuto del risultato in Markdown. Il tuo corpo di richiesta rimane JSON.

| Risposta | Accept | X-Respond-With | Utilizzare per |
| --- | --- | --- | --- |
| JSON | application/json | Omissione | Parsing campi in codice · default |
| JSON + Markdown | application/json | markdown | Contesto agente con metadati strutturati |
| Testo in bianco | text/plain | Omissione | Leggere i campi originali in un terminale |
| Testo + Markdown | text/plain | markdown | Metodati di lettura e Markdown insieme |


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

## Esempi di richiesta e risposta

Queste schede mostrano la stessa ricerca Google in ogni formato. Utilizzare Bash e cURL 7.76+ con FLASHDATA_API_KEY impostato su una chiave che consente google_search. Eseguire un comando invia una ricerca leggibile.

### JSON

Predefinito. Parsare l'array dei risultati; i campi all'interno di esso dipendono dalla fonte.

#### Richiesta · 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"}'
```

#### Esempio di risposta · valori illustrativi

```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

Leggi il contenuto come stringa Markdown. Sostituisce i risultati; fonte, stato e utilizzo rimangono disponibili come campi JSON.

#### Richiesta · 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"}'
```

#### Esempio di risposta · valori illustrativi

```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"
}
```


### Testo in bianco

Leggi la risposta come testo. Esso contiene i campi originali in un layout a tratti, non un documento JSON.

#### Richiesta · 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"}'
```

#### Esempio di risposta · valori illustrativi

```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"
```


### Testo + Markdown

Leggi la risposta come testo: i metadati prima, seguiti dal contenuto Markdown.

#### Richiesta · 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"}'
```

#### Esempio di risposta · valori illustrativi

```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\.
```


- [autenticazione API](https://flashdata.dev/it/docs/guides/headers-and-authentication/reference.md)
- [Google Cerca campi di risposta](https://flashdata.dev/it/docs/sources/google_search/reference.md#response)

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

## Endpoints supportati

Le stesse regole si applicano alle fonti di query Google Search e YouTube. Per YouTube Scarica, formattano il record di consegna, non il byte video o audio. API account, Bulk manifesta e parti NDJSON, callback e risposte MCP utilizzano i propri formati.

| Punto di arrivo | JSON / testo normale | Contenuto Markdown |
| --- | --- | --- |
| POST /v1/queries/realtime | Supportato | Supportato |
| GET /v2/jobs/{id}/results | Supportato | Supportato |
| POST /v1/queries | Ricevuta della sottomissione | Ignorato — selezionarlo quando si leggono i risultati |
| POST /v1/queries/batch | Ricevuta della sottomissione | Ignorato — selezionarlo quando si leggono i risultati |
| GET /v2/jobs/{id} | Situazione del lavoro | Ignorato — nessun contenuto di risultato qui |


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

## Formattare un risultato di lavoro completato

Impostare le intestazioni quando si legge il risultato, anche se li si imposta alla presentazione. Impostare JOB_ID per un lavoro completato che è possibile accedere. Questo GET legge i risultati esistenti senza presentare un'altra query.

| Formato richiesto | Rispondere ai risultati |
| --- | --- |
| originale JSON | 302 con uno storage firmato URL in Location. Prestare che URL separatamente, senza X-API-Key. Risultati memorizzati possono essere gzip-compressi. |
| Testo normale o l'opzione Markdown | 200 con il corpo formattato direttamente nella risposta. |

### Recuperare Markdown dentro 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'
```

- [Recuperare JSON originale · Python e cURL](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#results)

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

## Errori di formattazione

Gli errori API rimangono JSON o application/problem+json, anche quando si richiede un testo semplice. Controllare lo stato HTTP prima di analizzare il formato di successo.

| Stato / codice | Risolto |
| --- | --- |
| 400 · unsupported_representation | Utilizzare X-Respond-With: segnare o omettere l'intestazione. Valori come json o testo non sono supportati. |
| 406 · not_acceptable | Utilizzare Accept: application/json o text/plain. text/markdown e application/xml non sono supportati. |

- [Errori e codici di stato](https://flashdata.dev/it/docs/errors/reference.md)

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

## Dettagli dell'intestazione Accept

Omit Accept o invia */* per ottenere JSON. Le risposte usano UTF-8. Sono supportate gamme di media e pesi q; un charset non supportato restituisce 406 a meno che un altro range accettabile non corrisponda. Content-Type: application/json descrive il corpo della richiesta, non la risposta.

### Preferire il testo, consentire JSON

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

