# Landing Page Task API

Genera landing page in modo asincrono e consulta la cronologia delle attività.

Questa pagina documenta le API Felo esistenti `/v2`, usando **le entitlements dell'account Felo e le regole dei crediti Pro**. Se i crediti vengono scalati dipende dall'[operazione](https://openapi.felo.ai/it/docs/faq/billing-and-credits.md#regole-dei-crediti-per-funzionalit-v2). Per le chiamate con saldo della piattaforma, scegli un endpoint [Felo OpenAPI](https://openapi.felo.ai/it/docs/api-reference/openapi/overview.md) supportato; le forme di richiesta e risposta possono differire.

La Landing Page Task API fornisce funzionalità asincrone di generazione landing page. Prima crei un task, poi riutilizzi le API di polling del task esistenti per interrogare avanzamento e risultati.

## Usa con gli AI Agent

Installa il pacchetto completo `felo-ai` per consentire a un Agent di generare landing page e usare ogni altra Felo Skill disponibile. L'installer scopre dinamicamente ogni directory di pacchetto che contiene `SKILL.md`, invece di affidarsi a un elenco fisso. Installa tutte le Skill scoperte in Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills` o Hermes Agent `~/.hermes/skills`. Leggi la [guida manuale alla configurazione dell'AI Agent](https://openapi.felo.ai/it/docs/felo-skills.md) per i passaggi specifici della piattaforma su API key e verifica.


## Autenticazione

Tutte le richieste richiedono una API Key nell'header `Authorization`:

```
Authorization: Bearer YOUR_API_KEY
```

## Crea task Landing Page

### Endpoint

```
POST https://openapi.felo.ai/v2/landing_page
```

### Header della richiesta

| Header | Obbligatorio | Descrizione |
|--------|--------------|-------------|
| `Authorization` | Sì | La tua API Key nel formato `Bearer YOUR_API_KEY` |
| `Content-Type` | Sì | `application/json` o `multipart/form-data` |

### Body della richiesta

| Parametro | Tipo | Obbligatorio | Descrizione |
|-----------|------|--------------|-------------|
| `query` | string | Sì | Prompt della richiesta di generazione della landing page |
| `stream_protocol` | string | No | Protocollo di stream. Predefinito: `message_center_v1` |
| `livedoc_short_id` | string | No | Short ID LiveDoc esistente da usare come contesto |
| `resource_ids` | array di stringhe | No | ID risorsa LiveDoc da usare come contesto |

### Esempio

```bash
curl -X POST 'https://openapi.felo.ai/v2/landing_page' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Generate a landing page for Felo Search"
  }'
```

### Crea con file

Usa `multipart/form-data` per caricare un file insieme alla richiesta del task Landing Page. Il file viene caricato prima come risorsa LiveDoc, poi il suo ID risorsa viene passato al task Landing Page.

```bash
curl -X POST 'https://openapi.felo.ai/v2/landing_page' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'query=Generate a landing page from this product brief' \
  -F 'file=@brief.pdf'
```

Parti multipart opzionali:

| Parametro | Tipo | Obbligatorio | Descrizione |
|-----------|------|--------------|-------------|
| `stream_protocol` | string | No | Protocollo di stream. Predefinito: `message_center_v1` |
| `livedoc_short_id` | string | No | Short ID LiveDoc esistente. Se omesso, viene creato un nuovo LiveDoc |

### Risposta di successo (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "task_id": "019cad6d-e874-55ef-d577-686344b5a7e9"
  }
}
```

### Campi della risposta

| Campo | Tipo | Descrizione |
|-------|------|-------------|
| `task_id` | string | Identificatore del task asincrono per il polling successivo |

## Interroga lo stato del task

I task Landing Page riutilizzano le stesse API di polling del task dei PPT.

### Endpoint

```
GET https://openapi.felo.ai/v2/tasks/{task_id}/status
```

### Esempio

```bash
curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Interroga le informazioni storiche del task

### Endpoint

```
GET https://openapi.felo.ai/v2/tasks/{task_id}/historical
```

### Esempio

```bash
curl -X GET 'https://openapi.felo.ai/v2/tasks/019cad6d-e874-55ef-d577-686344b5a7e9/historical' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Esempio di risposta completata AI_PAGE

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "task_id": "019d7a4d-6ab5-a96d-0f98-43ca434ab621",
    "task_status": "COMPLETED",
    "ppt_biz_id": "9qiLTmT77fA3aVurrMHvRJ",
    "ppt_url": "https://felo.ai/slides/9qiLTmT77fA3aVurrMHvRJ",
    "ai_page_html": "https://api-ext-index-file.felo.ai/html/address?message_id=9qiLTmT77fA3aVurrMHvRJ"
  }
}
```

Consulta la [PPT Task API](https://openapi.felo.ai/it/api-reference/v2/ppt-tasks.html) per gli esempi di risposta di polling condivisi e la semantica degli stati.

## Codici di errore

| Codice | Stato HTTP | Descrizione |
|------|-------------|-------------|
| `INVALID_API_KEY` | 401 | La API Key è non valida o revocata |
| `LANDING_PAGE_TASK_CREATE_FAILED` | 502 | Creazione del task della landing page fallita |
| `INSUFFICIENT_CREDITS` | 402 | Crediti insufficienti disponibili |
