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

# Screenshot sincrono

> L'endpoint `screenshot` esegue una sessione del browser, esegue JavaScript e restituisce un'immagine codificata in base64 in una singola richiesta sincrona.

## Per iniziare

### URL base

```
https://screenshot.cleariflow.com/v1/screenshot
```

### Esempio di richiesta

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://cleariflow.com",
    "capture_full_page": true,
    "export_format": "jpeg"
  }'
```

Una richiesta riuscita restituisce lo screenshot in base64 e metadati:

<ResponseExample>
  ```json theme={"system"}
  {
    "ok": true,
    "image_base64": "/9j/4AAQSkZJRg...",
    "content_type": "image/jpeg",
    "meta": {
      "elapsed_ms": 4521
    }
  }
  ```
</ResponseExample>

Decodifica `image_base64` per ottenere i byte JPEG o PNG grezzi.

### Opzioni di rendering

L'oggetto `render` controlla come il browser carica la pagina prima della cattura. Tutti i campi sono opzionali — se omessi, si applicano i valori predefiniti del server.

```json theme={"system"}
"render": {
  "wait_until": "networkidle",
  "timeout_ms": 60000,
  "post_load_wait_ms": 2000,
  "ignore_https_errors": false,
  "full_page": true,
  "screenshot_format": "jpeg",
  "user_agent": "Mozilla/5.0 ...",
  "viewport": {
    "width": 1365,
    "height": 768
  }
}
```

| Campo                 | Tipo    | Predefinito        | Descrizione                                                                                                                                                               |
| --------------------- | ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wait_until`          | String  | `domcontentloaded` | Quando considerare la navigazione completata. Usa `domcontentloaded` per risultati più rapidi; `networkidle` se la pagina carica dati via XHR/fetch dopo l'HTML iniziale. |
| `timeout_ms`          | Integer | `60000`            | Tempo massimo in millisecondi di attesa del caricamento della pagina.                                                                                                     |
| `post_load_wait_ms`   | Integer | `0`                | Ritardo aggiuntivo in millisecondi dopo `wait_until` prima della cattura. Utile per animazioni o contenuti lazy-loaded.                                                   |
| `ignore_https_errors` | Boolean | `false`            | Se `true`, ignora errori del certificato TLS della pagina di destinazione.                                                                                                |
| `full_page`           | Boolean | `true`             | Se `true`, cattura l'intera altezza scrollabile della pagina.                                                                                                             |
| `screenshot_format`   | String  | `jpeg`             | Formato di output: `jpeg` o `png`.                                                                                                                                        |
| `user_agent`          | String  | —                  | Stringa User-Agent personalizzata per la sessione del browser.                                                                                                            |
| `viewport`            | Object  | `1365×768`         | Dimensione del viewport tramite `width` e `height` in pixel.                                                                                                              |

### Campi di convenienza

Questi campi di livello superiore sono alias uniti in `render` e `actions` per retrocompatibilità e richieste più semplici:

| Campo               | Mappa a                    | Descrizione                                                                     |
| ------------------- | -------------------------- | ------------------------------------------------------------------------------- |
| `capture_full_page` | `render.full_page`         | Attiva/disattiva cattura pagina intera.                                         |
| `width` / `height`  | `render.viewport`          | Dimensioni del viewport in pixel.                                               |
| `delay`             | `render.post_load_wait_ms` | Ritardo in **secondi** prima della cattura.                                     |
| `export_format`     | `render.screenshot_format` | `jpeg` o `png`.                                                                 |
| `user_agent`        | `render.user_agent`        | User-Agent personalizzato.                                                      |
| `css_injection`     | azione `inject_css`        | CSS iniettato prima della cattura quando non è presente un'azione `inject_css`. |

Esempio con campi piatti:

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_key": "YOUR_UNIQUE_API_KEY",
    "url": "https://cleariflow.com",
    "width": 1280,
    "height": 720,
    "delay": 2,
    "export_format": "png"
  }'
```

### Opzioni risorse

L'oggetto `resources` controlla quali tipi di risorse il browser carica durante la cattura. Bloccare risorse pesanti accelera le richieste quando la fedeltà visiva lo consente.

```json theme={"system"}
"resources": {
  "block": ["images", "fonts", "media"]
}
```

| Valore   | Blocca                         |
| -------- | ------------------------------ |
| `images` | Immagini (`<img>`, sfondi CSS) |
| `fonts`  | Web font                       |
| `media`  | Flussi video e audio           |

### Endpoint GET legacy

`GET /v1/` restituisce byte immagine grezzi (JPEG o PNG) invece di JSON. Passa i parametri come query string:

```
https://screenshot.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY&url=https://cleariflow.com&capture_full_page=true&export_format=jpeg
```

Parametri query supportati: `url`, `api_key`, `session_id`, `fingerprint`, `capture_full_page`, `width`, `height`, `delay`, `css_injection`, `user_agent`, `export_format`.

### Parametri di richiesta

<ParamField body="url" type="String" required>
  L'URL di destinazione da catturare. Deve essere un URL HTTP o HTTPS pubblico. Le richieste a localhost e indirizzi IP privati sono bloccate dalla protezione SSRF.
</ParamField>

<ParamField body="api_key" type="String" required>
  La tua chiave API univoca.
</ParamField>

<ParamField body="session_id" type="String">
  Identificatore di sessione opzionale per riutilizzare lo stato del browser (cookie, local storage) tra più richieste.
</ParamField>

<ParamField body="fingerprint" type="String">
  Preset dell'impronta del browser. Valori supportati: `desktop_en_us`, `desktop_ru_ru`, `mobile_en_us`.
</ParamField>

<ParamField body="render" type="Object">
  Opzioni di rendering e cattura per la sessione del browser.
</ParamField>

<ParamField body="render.wait_until" type="String">
  Quando considerare la navigazione completata. Valori: `domcontentloaded`, `networkidle`. Predefinito: `domcontentloaded`.
</ParamField>

<ParamField body="render.timeout_ms" type="Integer">
  Tempo massimo in millisecondi di attesa del caricamento della pagina. Predefinito: 60000.
</ParamField>

<ParamField body="render.post_load_wait_ms" type="Integer">
  Ritardo aggiuntivo in millisecondi dopo l'evento di caricamento della pagina prima della cattura.
</ParamField>

<ParamField body="render.ignore_https_errors" type="Boolean">
  Se `true`, ignora errori del certificato TLS della pagina di destinazione.
</ParamField>

<ParamField body="render.full_page" type="Boolean">
  Se `true`, cattura l'intera pagina scrollabile. Predefinito: `true`.
</ParamField>

<ParamField body="render.screenshot_format" type="String">
  Formato di output: `jpeg` o `png`. Predefinito: `jpeg`.
</ParamField>

<ParamField body="render.user_agent" type="String">
  User-Agent personalizzato per la sessione del browser.
</ParamField>

<ParamField body="render.viewport" type="Object">
  Dimensione del viewport con `width` e `height` in pixel.
</ParamField>

<ParamField body="resources" type="Object">
  Controlli di caricamento delle risorse.
</ParamField>

<ParamField body="resources.block" type="Array">
  Tipi di risorse da bloccare. Valori supportati: `images`, `fonts`, `media`.
</ParamField>

<ParamField body="actions" type="Array">
  Elenco ordinato di azioni del browser prima della cattura. Ogni azione è un oggetto con un campo `type`.
</ParamField>

<ParamField body="actions[].type" type="String" required>
  Tipo di azione. Valori supportati: `wait`, `wait_for`, `click`, `type`, `scroll`, `inject_css`.
</ParamField>

<ParamField body="actions[].selector" type="String">
  Selettore CSS per azioni `wait_for`, `click` o `type`.
</ParamField>

<ParamField body="actions[].text" type="String">
  Testo da digitare per l'azione `type`.
</ParamField>

<ParamField body="actions[].css" type="String">
  Stringa CSS per l'azione `inject_css`.
</ParamField>

<ParamField body="actions[].to" type="String">
  Destinazione dello scroll per l'azione `scroll` (es. `bottom`).
</ParamField>

<ParamField body="actions[].wait_ms" type="Integer">
  Durata in millisecondi per l'azione `wait`.
</ParamField>

<ParamField body="cookies" type="Array">
  Cookie da iniettare prima della navigazione. Ogni oggetto cookie richiede `name` e `value`; campi opzionali: `domain`, `path`.
</ParamField>

<ParamField body="capture_full_page" type="Boolean">
  Alias di convenienza per `render.full_page`.
</ParamField>

<ParamField body="width" type="Integer">
  Alias di convenienza per `render.viewport.width`.
</ParamField>

<ParamField body="height" type="Integer">
  Alias di convenienza per `render.viewport.height`.
</ParamField>

<ParamField body="delay" type="Integer">
  Ritardo in secondi prima della cattura. Mappato a `render.post_load_wait_ms`.
</ParamField>

<ParamField body="css_injection" type="String">
  CSS iniettato tramite un'azione `inject_css` quando non è già presente in `actions`.
</ParamField>

<ParamField body="export_format" type="String">
  Alias di convenienza per `render.screenshot_format`. Valori: `jpeg`, `png`.
</ParamField>

### Parametri di risposta

La risposta dell'API viene restituita in un [formato JSON](https://www.json.org/json-en.html) universale e leggero.

<ResponseField name="ok" type="Boolean">
  Se lo screenshot è stato completato con successo.
</ResponseField>

<ResponseField name="image_base64" type="String">
  Dati immagine codificati in base64. Decodifica per ottenere byte JPEG o PNG grezzi.
</ResponseField>

<ResponseField name="content_type" type="String">
  Tipo MIME dell'immagine (`image/jpeg` o `image/png`).
</ResponseField>

<ResponseField name="meta" type="Object">
  Metadati sulla cattura, incluso il tempo trascorso in millisecondi.
</ResponseField>

<ResponseField name="error" type="Object">
  Dettagli dell'errore quando `ok` è `false`.
</ResponseField>