> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

# Vettorizza immagini in serie con una coda API persistente

> Vettorizza immagini in serie con una coda persistente. Salva gli ID, gestisci i file con errori e riprendi il lavoro senza ripetere le conversioni finite.

Source: https://perfectvector.com/it/blog/batch-vectorize-images-api

Language: it
Author: Jay
Published: 2026-11-10T08:00:00+09:00

Per vettorizzare immagini in serie con un’API, metti i file sorgente in coda e salva lo stato di ciascuno prima di passare al successivo. Con PerfectVector API v1, il lotto è gestito dal tuo processo. L’API accetta un’immagine per richiesta e, per impostazione predefinita, consente una conversione live alla volta per account. [Limiti API di PerfectVector](https://perfectvector.com/docs/api/limits)

## Crea una riga nella coda per ogni immagine

Parti da una copia stabile di ogni originale e da una cartella di destinazione separata. Gli esempi presuppongono un solo processo, un database SQLite locale e una cartella con PNG, JPEG o WebP a fotogramma singolo. Controlla i [limiti dei file per l’API](https://perfectvector.com/docs/api/limits) prima di aggiungere le immagini alla coda. Usa percorsi di output univoci, così due file chiamati `logo.png` non si sovrascrivono.

Salva questi campi insieme prima di tentare il primo caricamento.

| Campo                  | Che cosa conservare                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Sorgente               | Percorso stabile o versione dell’oggetto, e hash dei byte originali.                                                           |
| Chiave della richiesta | Una chiave di idempotenza per riconoscere gli invii ripetuti della stessa operazione. Annota anche quando tenti la prima POST. |
| ID di conversione      | L’ID `vec_…` dell’API, salvato appena lo ricevi.                                                                               |
| Output                 | Una destinazione locale univoca e l’ultimo stato confermato nella coda.                                                        |
| Dettagli dell’errore   | Codice del problema API, ID della richiesta o errore di conversione, se disponibile.                                           |

Salva la riga nel database prima di inviare la POST. Se l’API accetta il file ma la connessione cade prima che arrivi l’ID, puoi riusare la chiave salvata. PerfectVector la riconosce per 24 ore dalla prima richiesta nello stesso account e nella stessa modalità. Nel nuovo invio mantieni gli stessi byte e le stesse opzioni. [Idempotenza di PerfectVector](https://perfectvector.com/docs/api/idempotency)

**Flusso di lavoro**

![Una pila di immagini raster con un’etichetta porta a una conversione registrata e poi a un SVG. Una freccia dal riavvio torna alla conversione salvata.](https://perfectvector.com/blog/batch-vectorize-images-api/workflow.webp)

*Salva l’ID della conversione prima del download. Se il lavoro si interrompe, riparti da quell’ID.*

## Invia, controlla e salva un risultato alla volta

Invia una POST multipart a `/v1/vectorizations` con l’immagine nel campo `image` e la chiave della riga nell’intestazione `Idempotency-Key`. Usa `Prefer: respond-async` per ottenere rapidamente la risposta. Salva l’ID restituito prima di controllare lo stato. Una risposta `202` indica che la conversione è in sospeso. Una `201` può descrivere una conversione riuscita o fallita: leggi lo stato nel JSON. [Attesa ed elaborazione asincrona di PerfectVector](https://perfectvector.com/docs/api/waiting-and-async)

Ecco come decide il processo. Uno stato della coda come `saved` è un’etichetta che definisci tu. L’API restituisce stati come `processing` e `succeeded`.

| Riga salvata sul disco              | Passaggio successivo                                                                                                                                                                          |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nuova, con la chiave salvata        | Invia i byte originali e registra l’ID di conversione restituito.                                                                                                                             |
| Invio incerto, ID sconosciuto       | Ripeti il caricamento con la chiave salvata entro la finestra prevista. Se è scaduta, segnala la riga per un controllo prima di avviare una nuova conversione che potrebbe essere addebitata. |
| ID di conversione salvato           | Controlla lo stato con l’ID esistente. Aspetta circa due secondi tra le richieste e rispetta le attese imposte dal limite di frequenza.                                                       |
| Conversione riuscita, file mancante | Scarica il risultato, verifica `image/svg+xml`, scrivilo in un file temporaneo e rinominalo nella destinazione finale. Segna la riga come salvata dopo la rinomina.                           |
| Salvata                             | Salta la POST. Se manca il file, prova a recuperare il risultato esistente finché il link è valido.                                                                                           |
| Rifiutata o fallita                 | Registra il problema HTTP o l’errore finale. Correggi un input non valido prima di riprovare come nuova operazione.                                                                           |

Se una POST restituisce `429` o `503`, rispetta `Retry-After` e riprova con gli stessi byte e le stesse opzioni usando la chiave originale entro 24 ore. Se il problema è `too_many_in_flight`, aspetta anche che la conversione live in corso finisca. Se hai un ID, controllalo prima di reinviare il file. Una conversione definitivamente `failed` con `timeout` o `provider_unavailable` richiede una nuova chiave se decidi di riprovare. Se il provider non è disponibile, aspetta che il servizio torni operativo. Un timeout del client lascia incerto lo stato della conversione: usa l’ID o ripeti la richiesta con la chiave originale entro la finestra prevista. [Errori API di PerfectVector](https://perfectvector.com/docs/api/errors)

Al riavvio, il processo può ripetere il controllo dello stato o il download senza avviare un’altra conversione. Scarica e conserva ogni SVG riuscito prima di passare alla riga successiva. Il risultato API scade 24 ore dopo la fine della conversione. [Risultati e download di PerfectVector](https://perfectvector.com/docs/api/results)

Adatta questo pseudocodice al database e al client HTTP. La prova qui sotto presuppone che il processo registri ogni richiesta e che, solo durante il test, possa fermarsi subito dopo aver salvato il secondo ID.

```text
for each queue row in a stable order:
    if the row is rejected or its saved SVG is still on disk:
        continue
    if the row has no conversion ID:
        verify source bytes match the stored digest
        if an earlier POST is uncertain and the replay window expired:
            flag the row for review and continue
        POST with the stored key and original bytes and options
        if the response is a permanent input rejection:
            commit the error and continue
        if the POST times out or the service requests a retry:
            keep the same key, record the retry time and stop this run
        commit the returned conversion ID
        pause here when testing recovery after a commit
    GET status by conversion ID, waiting between pending responses
    if conversion failed:
        commit its error and continue
    download the existing result and check the SVG media type
    write to a temporary file and rename it to the output path
    commit the saved state
```

## Prova il riavvio con tre file

Usa due piccoli loghi PNG e un PNG danneggiato. Lascia apposta il file danneggiato per vedere se la coda prosegue dopo il rifiuto. Con una chiave di test, i due file validi devono restituire un SVG di esempio. Quello danneggiato deve essere rifiutato durante la verifica e non deve produrre un file nella cartella di destinazione. La modalità di test restituisce lo stesso SVG per entrambi i file validi. [Modalità di test di PerfectVector](https://perfectvector.com/docs/api/test-mode)

1. Lascia che il primo file raggiunga `saved`. Metti in pausa il processo dopo aver scritto l’ID del secondo file valido e prima di averne salvato l’SVG.
2. Riavvia il processo. Verifica che salti il primo file e scarichi il secondo usando l’ID esistente.
3. Verifica che il file danneggiato compaia nel rapporto con il codice del problema e che non sia stato scritto alcun SVG per quel file.
4. Esegui il processo un’altra volta. Verifica che i due file salvati siano ancora al loro posto e che nessuno dei due venga ricaricato.

Abbiamo provato il riavvio con una chiave di test. Il processo ha salvato due SVG di esempio, registrato come rifiutato il file danneggiato e ripreso il secondo file valido tramite il suo ID. L’ultima esecuzione non ha inviato richieste. Per verificare lo stato in sospeso usa una risposta di prova: le conversioni di test terminano subito.

## Domande frequenti

### Posso inviare tutti i file con una sola chiamata API?

PerfectVector API v1 accetta un’immagine per POST. Invia il lotto come serie di richieste distinte. In modalità live, rispetta il limite di conversioni contemporanee e aspetta che quella attiva finisca prima di inviare la successiva. [Limiti API di PerfectVector](https://perfectvector.com/docs/api/limits)

### Che faccio se l’SVG è scaduto?

Usa l’SVG salvato se lo avevi scaricato. In caso contrario, controlla lo stato e decidi se avviare una nuova operazione. Una nuova conversione live può consumare un altro credito se riesce. [Risultati e download di PerfectVector](https://perfectvector.com/docs/api/results)

## Fonti

1. [PerfectVector — Limiti](https://perfectvector.com/docs/api/limits) — Verifica dei file e limite predefinito di conversioni contemporanee.
2. [PerfectVector — Idempotenza](https://perfectvector.com/docs/api/idempotency) — Ambito della chiave, finestra e corrispondenza degli input.
3. [PerfectVector — Attesa ed elaborazione asincrona](https://perfectvector.com/docs/api/waiting-and-async) — Invio asincrono e controllo dello stato.
4. [PerfectVector — Risultati](https://perfectvector.com/docs/api/results) — Download, errori e scadenza dei risultati.
5. [PerfectVector — Modalità di test](https://perfectvector.com/docs/api/test-mode) — Verifiche di caricamento e risultati che puoi provare con una chiave di test.
6. [PerfectVector — Errori](https://perfectvector.com/docs/api/errors) — Attese da Retry-After, errori definitivi e casi in cui serve una nuova chiave.

***

[Ottieni una chiave di test dalla pagina API di PerfectVector](https://perfectvector.com/it/api) e prova con tre tuoi file. Verifica che ogni riga riuscita abbia un SVG sul disco e che al riavvio non venga reinviata nessuna riga completata.

## Explore

- [Read the HTML article](https://perfectvector.com/it/blog/batch-vectorize-images-api)
- [Conversione in serie PNG2SVG: controlla lo ZIP scaricato](https://perfectvector.com/it/blog/png2svg-batch-convert.md)
- [Convertire una cartella di immagini in SVG con Claude Code](https://perfectvector.com/it/blog/batch-vectorize-images-claude-code-mcp.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)