# Configurazione API Felo

Configura gli endpoint Felo in Data API per ricerca, contenuti web, dati X e presentazioni, usando il saldo della piattaforma.

Felo è un provider in [Data API](https://openapi.felo.ai/it/docs/data-api), che offre ricerca web, lettura web, dati X, risposte basate sulla ricerca e presentazioni. Trova ciascun endpoint Felo insieme agli altri provider nella categoria Data API pertinente.

Questi endpoint usano **il saldo della piattaforma** e il prefisso `/api/v1/data`. Questa guida spiega l'autenticazione, la tua prima richiesta e dove trovare le regole di fatturazione.

Per usare i crediti Felo Pro, vedi le [API Felo esistenti](https://openapi.felo.ai/it/docs/api-reference/felo-apis.md). Il saldo della piattaforma e i crediti Pro sono separati.

## Effettua la tua prima richiesta

1. Crea una chiave in [Console → API Keys](https://openapi.felo.ai/console/api-keys).
2. Controlla o ricarica il tuo **saldo della piattaforma** in [Console → Billing](https://openapi.felo.ai/console/billing).
3. Imposta la chiave sul tuo server o nella tua shell locale:

```bash
export FELO_API_KEY="YOUR_API_KEY"
```

Invia `Authorization: Bearer $FELO_API_KEY`. È accettato anche `X-API-Key`; scegli un solo metodo di autenticazione. Le richieste JSON richiedono `Content-Type: application/json`.

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/web/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is retrieval augmented generation?","count":3}'
```

HTTP 200 restituisce un array `resources` con titoli delle pagine, link e snippet, più `total`. Non genera una risposta conversazionale; per quello usa [Chat](https://openapi.felo.ai/it/docs/data-api/guides/felo-chat.md).

## Esplora le API

| Guida | Operazioni | Cosa ricevi | Unità di fatturazione |
|---|---|---|---|
| [Ricerca Web](https://openapi.felo.ai/it/docs/data-api/guides/felo-web-search.md) | Cerca nel web | Titoli delle pagine, link e snippet | Richiesta |
| [Lettura Web](https://openapi.felo.ai/it/docs/data-api/guides/felo-web-read.md) | Leggi un URL | Markdown, testo, HTML o screenshot | Richiesta |
| [Dati X](https://openapi.felo.ai/it/docs/data-api/guides/felo-x-data.md) | Profili, ricerca utenti, post utente, ricerca post, risposte | Utenti e post strutturati, con paginazione dove supportata | Risultato restituito |
| [Chat basata sulla ricerca](https://openapi.felo.ai/it/docs/data-api/guides/felo-chat.md) | Rispondi a una domanda | Risposta e fonti web | Richiesta |
| [PPT](https://openapi.felo.ai/it/docs/data-api/guides/felo-ppt.md) | Crea, stato, risultati, esporta, stato esportazione, elimina | Task di generazione e PPTX scaricabile | Pagina generata; esportazione fatturata separatamente |
| [Fatturazione ed errori](https://openapi.felo.ai/it/docs/data-api/guides/felo-billing.md) | Guida di integrazione condivisa | Prezzi, gestione del saldo e regole di retry | — |

Ci sono **14 operazioni principali** in queste guide. Se la creazione PPT restituisce un `stream_key`, la [guida PPT](https://openapi.felo.ai/it/docs/data-api/guides/felo-ppt.md#leggi-gli-eventi-di-generazione-con-sse) spiega anche come leggere gli eventi di generazione con SSE. Le query di stato e risultato, le query di stato esportazione e l'eliminazione non creano un nuovo addebito.

## Prima di migrare un'integrazione esistente

Usa la guida per l'endpoint esatto che chiami. Sostituire `/v2` con `/api/v1/data` non è una migrazione completa:

- Web Read usa `/web/read`, con un solo formato di output per richiesta.
- Chat restituisce `status: "ok"`; supporta solo JSON non in streaming.
- I risultati PPT usano **POST** `/tasks/{task_id}/historical`.
- La creazione PPT restituisce gli identificatori alla radice JSON. Salva sia `task_id` sia `ppt_business_id`.
- I PPT generati scadono dopo sette giorni. Esporta e salva il file prima della scadenza.

Non esiste qui un equivalente OpenAPI nativo documentato per ogni workflow `/v2`, come LiveDoc CRUD, Mindmap o SuperAgent. Continua a usare le loro [guide Felo APIs](https://openapi.felo.ai/it/docs/api-reference/felo-apis.md) e la fatturazione a crediti Pro.

## Contratto e prezzi attuali

- [Schema OpenAPI pubblicato](https://openapi.felo.ai/api/v1/data/openapi.json) — definizioni dei campi e schemi di risposta.
- [Schema YAML OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.yaml) — per strumenti che accettano YAML.
- [Prezzi attuali](https://openapi.felo.ai/api/v1/data/prices) — ID operazione, unità di fatturazione e tariffe correnti.

Queste risorse sono pubbliche e possono essere lette senza una chiave. Consulta [Fatturazione ed errori](https://openapi.felo.ai/it/docs/data-api/guides/felo-billing.md) prima di aggiungere retry automatici.