Vettorizza un’immagine in Python con un’API

Uno script Python può inviare un’immagine raster all’API di vettorizzazione di PerfectVector e salvare l’SVG accanto all’originale. L’esempio qui sotto stampa l’ID della conversione prima del download. Se cade la connessione, quell’ID e una chiave che scegli per la richiesta ti offrono due modi per recuperare il risultato.

Provalo con la tua immagine

Apri lo strumento completo

PNGJPGWEBPPNGSVGRilascia qui la tua immagineo fai clic · incolla ⌘VSeleziona immagineRilascia per controllare l’immagine

Puoi provarlo gratis. Rilascia un’immagine e guarda l’anteprima del tuo vettoriale, senza registrarti.

Procurati una chiave di test e un’immagine

Crea una chiave di test dalla pagina Developer API. Impostala nel terminale come PERFECTVECTOR_API_KEY e tienila fuori dallo script e dal controllo di versione. Installa Requests nell’ambiente Python del progetto con python -m pip install requests.

Per la prima prova usa un PNG, JPEG o WebP a fotogramma singolo, per esempio un logo da 512 × 512 chiamato logo.png. L’API accetta file fino a 5 MiB e immagini con ciascun lato da 100 a 4096 pixel. La modalità di test verifica il caricamento e restituisce gratuitamente un SVG fisso con la scritta «TEST MODE». Quel file serve a verificare richiesta e download. Per valutare la qualità del tracciamento usa una conversione live della tua immagine. Modalità di test dell’API PerfectVector

Abbiamo eseguito lo script con una chiave di test, scaricato un SVG valido e ripetuto lo stesso caricamento con la stessa chiave di richiesta. Entrambe le esecuzioni hanno restituito lo stesso ID di conversione.

Flusso di lavoro

Invia l’immagine e salva l’SVG con Python

Salva questo codice come vectorize.py. L’argomento files dice a Requests di creare un caricamento multipart, con i byte originali nel campo image. Caricamenti multipart con Requests

import os
import sys
import time
from pathlib import Path
 
import requests
 
API = "https://api.perfectvector.com/v1"
AUTH = {"Authorization": f"Bearer {os.environ['PERFECTVECTOR_API_KEY']}"}
 
 
def checked(response):
    content_type = response.headers.get("Content-Type", "").split(";")[0]
    if response.status_code >= 400 and content_type == "application/problem+json":
        problem = response.json()
        raise RuntimeError(f"{problem['code']} (request {problem['request_id']})")
    response.raise_for_status()
    return response
 
 
def vectorize(source, destination, operation_id):
    with source.open("rb") as image:
        response = checked(requests.post(
            f"{API}/vectorizations",
            headers={**AUTH, "Idempotency-Key": operation_id, "Prefer": "wait=10"},
            files={"image": (source.name, image)},
            timeout=30,
        ))
 
    conversion = response.json()
    conversion_id = conversion["id"]
    print(f"Conversion ID: {conversion_id}", flush=True)
    deadline = time.monotonic() + 720
    while conversion["status"] in {"queued", "processing"}:
        if time.monotonic() >= deadline:
            raise TimeoutError(f"Stopped polling {conversion_id}")
        time.sleep(2)
        conversion = checked(requests.get(
            f"{API}/vectorizations/{conversion_id}", headers=AUTH, timeout=30,
        )).json()
 
    if conversion["status"] != "succeeded":
        error = conversion["results"][0].get("error") or {}
        raise RuntimeError(f"{conversion_id}: {error.get('code', conversion['status'])}")
 
    svg = checked(requests.get(
        f"{API}/vectorizations/{conversion_id}/result", headers=AUTH, timeout=30,
    ))
    if svg.headers.get("Content-Type", "").split(";")[0] != "image/svg+xml":
        raise ValueError("Expected an SVG response")
    partial = destination.with_suffix(".svg.part")
    partial.write_bytes(svg.content)
    partial.replace(destination)
    print(f"{destination} saved ({len(svg.content)} bytes)")
 
 
if __name__ == "__main__":
    source = Path(sys.argv[1])
    if source.suffix.lower() not in {".png", ".jpg", ".jpeg", ".webp"}:
        raise SystemExit("Choose a PNG, JPEG or WebP file")
    if source.stat().st_size > 5 * 1024 * 1024:
        raise SystemExit("Choose a file no larger than 5 MiB")
    vectorize(source, source.with_suffix(".svg"), sys.argv[2])

Esegui il comando nella directory che contiene logo.png. Scegli e annota un ID per l’operazione prima di lanciarlo. L’API lo chiama chiave di idempotenza: permette di associare gli invii ripetuti dello stesso file a una sola conversione. L’esempio usa logo-asset-0001. Usa un valore diverso per un’altra immagine o operazione. Tentativi sicuri con PerfectVector

python vectorize.py logo.png logo-asset-0001

Una prova riuscita stampa l’ID della conversione e il numero di byte, e lascia logo.svg accanto a logo.png. Apri logo.svg per verificare che il campione venga visualizzato. Lo script sostituisce un SVG esistente con lo stesso nome dopo aver scaricato quello nuovo. Per la prima prova usa una cartella temporanea.

Lo script chiede al server di attendere fino a 10 secondi prima di restituire una conversione non finita. Controlla ogni due secondi circa le conversioni queued e processing e scarica solo in stato succeeded. Una conversione di test termina subito. Prima di usare lo script in produzione, prova la parte che controlla lo stato con una risposta locale di esempio ancora in corso. Attesa ed elaborazione asincrona di PerfectVector

Recupera una conversione dopo un timeout

Se Python ha stampato un ID, controllalo con GET /v1/vectorizations/{id}. Quando la conversione riesce, usa GET /v1/vectorizations/{id}/result nello stesso account e modalità per scaricare l’SVG. Il link scade 24 ore dopo il completamento: conserva una copia se ti servirà. Download dei risultati PerfectVector

Se Python si è fermato prima di stampare l’ID, ripeti il comando con gli stessi byte e la stessa chiave entro 24 ore dalla prima richiesta. Se l’API aveva accettato il primo invio, restituisce la conversione esistente. Dopo quella finestra, un invio con la stessa chiave può avviarne un’altra. Tentativi sicuri con PerfectVector

Se devi contattare l’assistenza, conserva l’ID della richiesta riportato nell’eccezione o l’ID di conversione stampato dallo script. La guida agli errori API indica quali richieste puoi ripetere in sicurezza.

Domande frequenti

Posso vettorizzare JPEG o WebP con lo stesso script Python?

Sì. Passa il file JPEG o WebP come primo argomento. Valgono gli stessi limiti di peso e dimensioni e la stessa regola sul fotogramma singolo. L’output ha estensione SVG.

Posso usare questo esempio Python per un’intera cartella?

Usalo prima per verificare un caricamento e un download. Per una cartella, registra in una coda persistente la chiave, l’ID e il percorso di output di ogni file. Per impostazione predefinita PerfectVector consente una sola conversione live alla volta per account. Aspetta che termini prima di inviare la successiva. Limiti API di PerfectVector

Fonti

1. Requests — Guida rapida — File multipart, timeout e byte della risposta.
2. PerfectVector — Modalità di test — Limiti di caricamento, SVG fisso e crediti in modalità di test.
3. PerfectVector — Attesa ed elaborazione asincrona — Attesa lato server, controllo dello stato e completamento dei test.
4. PerfectVector — Idempotenza — Durata e ambito della chiave, conflitti e ripetizione delle richieste.
5. PerfectVector — Risultati — Endpoint del risultato, autenticazione e scadenza.
6. PerfectVector — Errori — Codici di errore HTTP e istruzioni per il recupero.
7. PerfectVector — Limiti — Limite predefinito di conversioni live e requisiti dei file.

Ottieni una chiave di test dalla pagina API di PerfectVector, esegui lo script su una tua immagine e verifica che l’SVG si apra e che il terminale mostri l’ID della conversione.