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

# Cómo vectorizar una imagen en Python con una API

> Envía un PNG, JPEG o WebP desde Python a una API de vectorización. Guarda el SVG, comprueba una respuesta de prueba y recupera la conversión si se corta la conexión.

Source: https://perfectvector.com/es/blog/vectorize-image-python-api

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

Un script de Python puede enviar una imagen rasterizada a la API de PerfectVector y guardar el SVG junto al original. El ejemplo imprime el ID de conversión antes de descargar el archivo. Si se interrumpe la conexión, puedes recuperar el resultado con ese ID o con la clave de solicitud que hayas elegido.

## Consigue una clave de prueba y una imagen

Crea una clave de prueba en la [página de la API para desarrolladores](https://perfectvector.com/account/developers). Configúrala en la terminal como `PERFECTVECTOR_API_KEY` y mantenla fuera del script y del control de versiones. Instala Requests en el entorno de Python del proyecto con `python -m pip install requests`.

Para la primera ejecución, usa un PNG, JPEG o WebP de un solo fotograma, como un logotipo de 512 × 512 llamado `logo.png`. La API admite archivos de hasta 5 MiB e imágenes de 100 a 4096 píxeles por lado. El modo de prueba valida la subida y devuelve sin costo un SVG fijo con la marca «TEST MODE». Ese archivo permite comprobar la solicitud y la descarga. Para evaluar la calidad del trazado, convierte tu imagen en producción. [Modo de prueba de la API de PerfectVector](https://perfectvector.com/docs/api/test-mode)

Ejecutamos el script con una clave de prueba, descargamos un SVG válido y repetimos la subida con la misma clave de solicitud. Las dos ejecuciones devolvieron el mismo ID de conversión.

**Esquema del proceso**

![Un archivo rasterizado local viaja en una solicitud identificada a un servicio en la nube y vuelve como archivo vectorial al disco.](https://perfectvector.com/blog/vectorize-image-python-api/workflow.webp)

*Guarda la clave junto con la subida y registra el ID de conversión antes de descargar el SVG.*

## Envía la imagen y guarda el SVG desde Python

Guarda el siguiente código como `vectorize.py`. El argumento `files` indica a Requests que prepare una subida multipart, que incluye los datos originales en el campo de formulario `image`. [Subidas multipart con Requests](https://requests.readthedocs.io/en/latest/user/quickstart/#post-a-multipart-encoded-file)

```python
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])
```

Ejecuta el comando desde el directorio que contiene `logo.png`. Elige un identificador para la conversión y anótalo antes de ejecutar el comando. La API lo llama *clave de idempotencia*. Es un valor que vincula los reenvíos de una misma subida a una sola conversión. El ejemplo usa `logo-asset-0001`. Usa otro valor para otra imagen u operación. [Reintentos seguros en PerfectVector](https://perfectvector.com/docs/api/idempotency)

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

Una prueba correcta imprime el ID y el número de bytes, y guarda `logo.svg` junto a `logo.png`. Abre `logo.svg` para comprobar que la muestra se ve bien. El script reemplaza un SVG del mismo nombre después de descargar el archivo nuevo. Haz la primera prueba en una carpeta temporal.

El script pide al servidor que espere hasta 10 segundos antes de devolver una conversión sin terminar. Consulta estados `queued` y `processing` aproximadamente cada dos segundos y descarga el SVG solo al recibir `succeeded`. Las conversiones de prueba terminan al instante. Usa una respuesta local simulada sin terminar para probar la consulta antes de emplearla en producción. [Espera y solicitudes asíncronas en PerfectVector](https://perfectvector.com/docs/api/waiting-and-async)

## Recupera una conversión tras agotar el tiempo de espera

Si Python ya imprimió el ID de conversión, consúltalo con `GET /v1/vectorizations/{id}`. Cuando termine correctamente, usa `GET /v1/vectorizations/{id}/result` en la misma cuenta y modo para descargar el SVG. El enlace caduca 24 horas después del fin de la conversión. Copia el archivo a tu almacenamiento si lo necesitas más adelante. [Descarga de resultados de PerfectVector](https://perfectvector.com/docs/api/results)

Si Python se detuvo antes de imprimir el ID, repite el comando con los mismos datos y la misma clave de idempotencia dentro de 24 horas desde la primera solicitud. La API devuelve la conversión existente si aceptó el envío original. Una vez pasado el plazo, la misma clave puede iniciar una conversión nueva. [Reintentos seguros en PerfectVector](https://perfectvector.com/docs/api/idempotency)

| Qué aparece                                        | Qué revisar                                                                                                                                      |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 invalid_api_key`                              | Configura una clave de prueba vigente en el entorno que usa Python. Si revocaste la clave, crea otra en el mismo modo.                           |
| `415 unsupported_media_type` o `422 invalid_image` | Abre el original y comprueba el formato real y las dimensiones en píxeles. Guarda la imagen corregida y asigna su propia clave al nuevo envío.   |
| Un ID de conversión seguido de `processing_failed` | La API registró una conversión, pero no pudo vectorizar la imagen. Revisa el original y reintenta con una imagen corregida como operación nueva. |
| `409 idempotency_conflict`                         | Usaste la misma clave con otros datos u opciones. Recupera la conversión con el archivo original o asigna una clave nueva a la entrada nueva.    |

Si necesitas contactar con soporte, conserva el ID de solicitud de la excepción o el ID de conversión que imprimió el script. La [referencia de errores de la API](https://perfectvector.com/docs/api/errors) explica cuándo es seguro reintentar.

## Preguntas frecuentes

### ¿Python puede vectorizar un JPEG o WebP con el mismo script?

Sí. Pasa el JPEG o WebP como primer argumento. Se aplican los mismos requisitos de tamaño, dimensiones y fotograma único. La salida tiene extensión SVG.

### ¿Puedo usar el ejemplo de Python para toda una carpeta?

Úsalo primero para comprobar una subida y una descarga. Para una carpeta, registra la clave, el ID de conversión y la ruta de salida de cada archivo en una cola persistente. PerfectVector admite por defecto una conversión en producción a la vez por cuenta. Espera a que termine cada una antes de enviar la siguiente. [Límites de la API de PerfectVector](https://perfectvector.com/docs/api/limits)

## Fuentes

1. [Requests — Inicio rápido](https://requests.readthedocs.io/en/latest/user/quickstart/) — Archivos multipart, tiempos de espera y datos binarios de respuesta.
2. [PerfectVector — Modo de prueba](https://perfectvector.com/docs/api/test-mode) — Límites de subida, SVG de muestra y créditos en pruebas.
3. [PerfectVector — Espera y solicitudes asíncronas](https://perfectvector.com/docs/api/waiting-and-async) — Preferencia de espera, consulta de estado y finalización de solicitudes de prueba.
4. [PerfectVector — Idempotencia](https://perfectvector.com/docs/api/idempotency) — Vigencia, alcance, conflictos y reglas de reenvío de claves.
5. [PerfectVector — Resultados](https://perfectvector.com/docs/api/results) — Punto de conexión, autenticación y caducidad.
6. [PerfectVector — Errores](https://perfectvector.com/docs/api/errors) — Códigos de problema HTTP y pasos para recuperar solicitudes.
7. [PerfectVector — Límites](https://perfectvector.com/docs/api/limits) — Simultaneidad en producción y límites de archivo.

***

[Consigue una clave de prueba en la página de la API de PerfectVector](https://perfectvector.com/es/api) y ejecuta el script con una imagen propia. Comprueba que el SVG guardado se abre y que la terminal imprime el ID de conversión.

## Explore

- [Read the HTML article](https://perfectvector.com/es/blog/vectorize-image-python-api)
- [Mejores vectorizadores con IA de 2026: opciones por uso](https://perfectvector.com/es/blog/best-ai-vectorizers-2026.md)
- [Convierte una carpeta a SVG por lotes con Claude Code](https://perfectvector.com/es/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)