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

# Vectorizar imágenes por lotes con una cola de API

> Vectoriza imágenes por lotes con una API y una cola persistente. Guarda los ID, gestiona fallos y reanuda una ejecución sin volver a enviar trabajos completados.

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

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

Para vectorizar imágenes por lotes con una API, registra cada archivo en una cola y guarda su progreso antes de pasar al siguiente. Con PerfectVector API v1, tu proceso gestiona el lote. La API admite una imagen por solicitud y, por defecto, una conversión en producción a la vez por cuenta. [Límites de la API de PerfectVector](https://perfectvector.com/docs/api/limits)

## Crea un registro en la cola para cada imagen

Empieza con una copia estable de cada original y una carpeta de salida independiente. Los ejemplos usan un solo proceso, una base local SQLite y una carpeta de PNG, JPEG o WebP de un solo fotograma. Comprueba los [límites de archivos de la API](https://perfectvector.com/docs/api/limits) antes de añadirlos a la cola. Usa rutas de salida únicas para que dos originales llamados `logo.png` no sobrescriban sus resultados.

Guarda juntos estos campos antes de intentar la primera subida.

| Campo              | Qué guardar                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| Origen             | Una ruta estable o versión de objeto, y un hash de los datos originales.                                        |
| Clave de solicitud | Una clave de idempotencia que identifica los reenvíos de la operación. Registra cuándo intentas el primer POST. |
| ID de conversión   | El ID `vec_…` de la API, guardado en cuanto llega.                                                              |
| Salida             | Un destino local único y el último estado confirmado del registro.                                              |
| Detalles del fallo | El código de problema de la API, el ID de solicitud o el error de conversión, si están disponibles.             |

Confirma el registro en la base de datos antes del POST. Si la API acepta la subida y se corta la conexión antes de recibir el ID, aún tienes la clave para repetirla. PerfectVector la reconoce durante 24 horas desde la primera solicitud en la misma cuenta y modo. Mantén los datos y las opciones al reenviar. [Idempotencia de PerfectVector](https://perfectvector.com/docs/api/idempotency)

**Esquema del proceso**

![Un grupo de imágenes rasterizadas con etiquetas conduce a un registro de conversión guardado y después a un SVG. Una flecha lleva del reinicio al registro.](https://perfectvector.com/blog/batch-vectorize-images-api/workflow.webp)

*Guarda el ID de conversión antes de descargar. Si hay una interrupción, reanuda el trabajo con ese ID.*

## Envía, consulta y guarda un trabajo a la vez

Envía un POST multipart a `/v1/vectorizations` con la imagen en el campo `image` y el encabezado `Idempotency-Key` del registro. Usa `Prefer: respond-async` para que el envío sea breve. Guarda el ID de la respuesta antes de consultar el estado. Una respuesta `202` indica que la conversión está pendiente. Una respuesta `201` puede describir un éxito o un fallo. Lee el estado en el JSON. [Espera y solicitudes asíncronas en PerfectVector](https://perfectvector.com/docs/api/waiting-and-async)

Este es el orden de decisiones del proceso. Un estado de cola como `saved` es una etiqueta propia. La API devuelve estados como `processing` y `succeeded`.

| Registro guardado                     | Siguiente acción                                                                                                                                                               |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Nuevo, con clave guardada             | Sube los datos originales y registra el ID de conversión devuelto.                                                                                                             |
| Envío incierto, ID desconocido        | Reenvía los mismos datos con la clave guardada dentro del plazo. Si pasó el plazo, marca el registro para revisión antes de intentar una conversión nueva que podría cobrarse. |
| ID de conversión guardado             | Consulta el ID existente. Espera unos dos segundos entre consultas y respeta las demoras por límites de solicitudes.                                                           |
| Conversión correcta, falta el archivo | Descarga el resultado, comprueba `image/svg+xml`, escríbelo en un archivo temporal y renómbralo para moverlo al destino. Marca el registro como guardado después de renombrar. |
| Guardado                              | Omite el POST. Si falta el archivo, intenta recuperar el resultado existente mientras funcione el enlace.                                                                      |
| Rechazado o fallido                   | Registra el problema HTTP o el error final de conversión. Corrige la entrada antes de enviarla como una operación nueva.                                                       |

Si un POST devuelve `429` o `503`, respeta `Retry-After` y reintenta con la misma imagen, las mismas opciones y la clave original dentro de las 24 horas. Con `too_many_in_flight`, espera además a que termine la conversión en producción existente. Si tienes un ID, consúltalo antes de volver a enviar. Una conversión con estado final `failed` y error `timeout` o `provider_unavailable` necesita una clave nueva si decides reintentar. Si el proveedor no está disponible, espera a que se recupere. Cuando el cliente agota la espera, el estado del primer envío queda incierto. Usa el ID o repite la solicitud con su clave original dentro del plazo. [Errores de la API de PerfectVector](https://perfectvector.com/docs/api/errors)

Después de reiniciar, el proceso puede volver a consultar el estado o descargar un resultado sin iniciar otra conversión. Descarga y guarda cada SVG correcto antes de avanzar en la cola. Los resultados de la API caducan 24 horas después de completarse la conversión. [Resultados y descargas de PerfectVector](https://perfectvector.com/docs/api/results)

Usa este pseudocódigo con tu base de datos y cliente HTTP. La prueba presupone que el proceso registra todas las solicitudes y puede pausar en modo de prueba justo después de confirmar el segundo ID de conversión.

```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
```

## Prueba el reinicio con tres archivos

Usa dos logotipos pequeños en PNG y un PNG dañado. Incluye el archivo dañado para comprobar si la cola avanza tras el rechazo. Con una clave de prueba, los dos archivos válidos deben devolver SVG de muestra. El archivo dañado debe fallar en la validación y quedar fuera de la carpeta de salida. El modo de prueba devuelve el mismo SVG para ambos archivos válidos. [Modo de prueba de PerfectVector](https://perfectvector.com/docs/api/test-mode)

1. Deja que el primer archivo llegue a `saved`. Pausa el proceso después de guardar el ID del segundo archivo válido y antes de guardar su salida.
2. Reinicia el proceso. Comprueba que omite el primer archivo y descarga el segundo con su ID de conversión existente.
3. Confirma que el archivo dañado aparece en el informe de errores con su código y que no se escribió un SVG para él.
4. Ejecuta el proceso otra vez. Confirma que los dos archivos guardados siguen en su sitio y que ninguno de sus envíos se repite.

Ejecutamos la prueba de reinicio con una clave de prueba de la API. Guardó dos SVG de muestra, registró un archivo dañado como rechazado y reanudó el segundo trabajo correcto mediante su ID existente. La última ejecución no hizo solicitudes. Usa una respuesta de prueba local para probar la ruta pendiente, pues las conversiones de prueba terminan al instante.

## Preguntas frecuentes

### ¿Puedo enviar todos los archivos en una llamada a la API?

PerfectVector API v1 admite una imagen en cada POST. Envía el lote como una serie de solicitudes. En producción, respeta el límite de conversiones en curso por cuenta y espera a que termine la actual antes de enviar la siguiente. [Límites de la API de PerfectVector](https://perfectvector.com/docs/api/limits)

### ¿Qué pasa si el SVG ya caducó?

Usa la copia guardada si ya lo descargaste. Si no, consulta el estado y decide si iniciar una operación nueva. Una nueva conversión en producción puede consumir otro crédito si termina correctamente. [Resultados y descargas de PerfectVector](https://perfectvector.com/docs/api/results)

## Fuentes

1. [PerfectVector — Límites](https://perfectvector.com/docs/api/limits) — Validación de archivos y límite predeterminado de simultaneidad por cuenta.
2. [PerfectVector — Idempotencia](https://perfectvector.com/docs/api/idempotency) — Alcance de la clave, plazo y coincidencia de las entradas.
3. [PerfectVector — Espera y solicitudes asíncronas](https://perfectvector.com/docs/api/waiting-and-async) — Envíos asíncronos y consultas de estado.
4. [PerfectVector — Resultados](https://perfectvector.com/docs/api/results) — Descargas, fallos y caducidad del resultado.
5. [PerfectVector — Modo de prueba](https://perfectvector.com/docs/api/test-mode) — Comprobaciones de subida y resultados con la clave de prueba.
6. [PerfectVector — Errores](https://perfectvector.com/docs/api/errors) — Demoras de Retry-After, fallos definitivos y cuándo usar una nueva clave.

***

[Consigue una clave de prueba en la página de la API de PerfectVector](https://perfectvector.com/es/api) y haz una prueba con tres archivos propios. Comprueba que cada registro correcto tenga un SVG guardado y que el reinicio no vuelva a enviar los trabajos completados.

## Explore

- [Read the HTML article](https://perfectvector.com/es/blog/batch-vectorize-images-api)
- [Conversión por lotes con PNG2SVG: revisa el ZIP descargado](https://perfectvector.com/es/blog/png2svg-batch-convert.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)