> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions. # Vetorizar imagens em lote com uma fila de API > Use uma API e uma fila persistente para vetorizar imagens em lote. Salve os IDs, trate falhas e retome um lote sem reenviar trabalhos concluídos. Source: https://perfectvector.com/pt-BR/blog/batch-vectorize-images-api Language: pt-BR Author: Jay Published: 2026-11-10T08:00:00+09:00 Para vetorizar imagens em lote por API, coloque cada arquivo de origem em uma fila e salve seu progresso antes de passar ao próximo. Na API v1 do PerfectVector, seu processo é responsável pelo lote. Por padrão, a API aceita uma imagem por requisição e uma conversão em produção por vez em cada conta. [Limites da API do PerfectVector](https://perfectvector.com/docs/api/limits) ## Crie um registro na fila para cada imagem Comece com uma cópia estável de cada origem e uma pasta separada para a saída. Os exemplos usam um processo, um banco SQLite local e uma pasta com PNG, JPEG ou WebP de quadro único. Confira os [limites de arquivo da API](https://perfectvector.com/docs/api/limits) antes de incluir arquivos na fila. Dê a cada saída um caminho único para que dois arquivos `logo.png` não sobrescrevam seus resultados. Salve os campos a seguir juntos antes de tentar o primeiro upload. | Campo | O que guardar | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | Origem | Um caminho estável ou uma versão do objeto e um hash dos dados originais. | | Chave de requisição | Uma chave de idempotência que identifica repetições da operação. Registre quando fez a primeira tentativa de POST. | | ID de conversão | O ID `vec_…` da API, assim que chegar. | | Saída | Um destino local exclusivo e o último estado confirmado na fila. | | Detalhes da falha | O código de erro da API, o ID da requisição ou o erro da conversão, quando disponíveis. | Confirme o registro no banco antes de enviar o POST. Se a API aceitar o upload e a conexão cair antes de você receber o ID, ainda haverá uma chave para reutilizar. O PerfectVector reconhece essa chave por 24 horas após a primeira requisição na mesma conta e modo. Mantenha os dados e as opções iguais ao repetir. [Idempotência no PerfectVector](https://perfectvector.com/docs/api/idempotency) **Diagrama do fluxo** ![Um grupo identificado de imagens rasterizadas leva a um registro de conversão salvo e depois a um SVG. Uma seta liga o reinício ao registro salvo.](https://perfectvector.com/blog/batch-vectorize-images-api/workflow.webp) *Salve o ID de conversão antes de baixar. Se houver uma interrupção, retome a partir desse ID.* ## Envie, consulte e salve um trabalho por vez Envie um POST multipart a `/v1/vectorizations` com a imagem no campo `image` e o cabeçalho `Idempotency-Key` do registro. Use `Prefer: respond-async` para um envio breve. Salve o ID de uma resposta bem-sucedida antes de consultar o status. A resposta `202` indica que a conversão está pendente. A resposta `201` pode indicar sucesso ou falha. Leia o status no JSON. [Espera e requisições assíncronas no PerfectVector](https://perfectvector.com/docs/api/waiting-and-async) Esta é a sequência de decisões do processo. Um estado da fila como `saved` é um rótulo seu. A API retorna status como `processing` e `succeeded`. | Registro da fila em disco | Próxima ação do processo | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Novo, com a chave salva | Envie os dados originais e registre o ID de conversão retornado. | | Envio incerto, ID desconhecido | Repita o mesmo upload com a chave salva dentro do prazo. Se o prazo tiver passado, sinalize o registro para revisão antes de tentar uma nova conversão que possa ser cobrada. | | ID de conversão salvo | Consulte o ID existente. Espere cerca de dois segundos entre consultas e respeite os intervalos impostos pelos limites de requisições. | | Conversão concluída, arquivo ausente | Baixe o resultado, confira `image/svg+xml`, grave em um arquivo temporário e renomeie para o destino. Marque como salvo depois de renomear. | | Salvo | Pule o POST. Se a saída sumir, tente baixar o resultado existente enquanto o link estiver válido. | | Rejeitado ou com falha | Registre o problema HTTP ou o erro final da conversão. Corrija uma entrada inválida antes de enviá-la como nova operação. | Se o POST retornar `429` ou `503`, respeite `Retry-After` e reenvie a mesma imagem com as mesmas opções e a chave original dentro das 24 horas. Em caso de `too_many_in_flight`, espere também a conversão em produção terminar. Se você tem um ID, consulte-o antes de reenviar. Uma conversão com estado final confirmado `failed` e erro `timeout` ou `provider_unavailable` exige outra chave se você decidir tentar de novo. Quando o prestador estiver indisponível, espere o serviço voltar. Se o cliente atingir o tempo limite, o resultado original será incerto. Use o ID ou repita a requisição com a chave original dentro do prazo. [Erros da API do PerfectVector](https://perfectvector.com/docs/api/errors) Após reiniciar, o processo pode consultar o status ou baixar o resultado outra vez sem iniciar uma conversão. Baixe e guarde cada SVG bem-sucedido antes de avançar na fila. O resultado da API expira 24 horas após a conclusão. [Resultados e downloads do PerfectVector](https://perfectvector.com/docs/api/results) Use o pseudocódigo com seu banco e cliente HTTP. O teste pressupõe que o processo registra cada requisição e pode pausar em modo de teste logo depois de confirmar o segundo ID de conversão. ```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 ``` ## Teste o reinício com três arquivos Use dois logos pequenos em PNG e um PNG danificado. Inclua o danificado para verificar se a fila avança após a rejeição. Com a chave de teste, os dois arquivos válidos devem retornar SVGs de exemplo. O arquivo danificado deve falhar na validação e ficar fora da pasta de saída. O modo de teste retorna o mesmo SVG para os dois arquivos válidos. [Modo de teste do PerfectVector](https://perfectvector.com/docs/api/test-mode) 1. Deixe o primeiro arquivo chegar a `saved`. Pause o processo depois de gravar o ID do segundo arquivo válido e antes de salvar a saída. 2. Reinicie o processo. Confirme que ele pula o primeiro arquivo e baixa o segundo com o ID de conversão existente. 3. Confirme que o arquivo danificado aparece no relatório com seu código de erro e que nenhum SVG foi gravado para ele. 4. Execute o processo outra vez. Confirme que os dois arquivos continuam salvos e que nenhum envio bem-sucedido foi repetido. Rodamos o teste de reinício com uma chave de teste da API. O processo salvou dois SVGs de exemplo, registrou a rejeição de um arquivo danificado e retomou a segunda conversão bem-sucedida com o ID existente. A última execução não fez requisições. Use uma resposta simulada localmente para testar a condição pendente, pois as conversões de teste terminam na hora. ## Perguntas frequentes ### Posso enviar todos os arquivos em uma chamada à API? A API v1 do PerfectVector aceita uma imagem por POST. Envie um lote como uma série de requisições separadas. Em produção, respeite o limite da conta e espere a conversão atual terminar antes de enviar a próxima. [Limites da API do PerfectVector](https://perfectvector.com/docs/api/limits) ### E se o SVG já tiver expirado? Use a cópia que salvou se já tiver baixado. Caso contrário, confira o status e decida se deve iniciar outra operação. Uma nova conversão em produção pode usar outro crédito se terminar com sucesso. [Resultados e downloads do PerfectVector](https://perfectvector.com/docs/api/results) ## Fontes 1. [PerfectVector — Limites](https://perfectvector.com/docs/api/limits) — Validação de arquivos e limite padrão de simultaneidade por conta. 2. [PerfectVector — Idempotência](https://perfectvector.com/docs/api/idempotency) — Escopo da chave, prazo de repetição e dados idênticos. 3. [PerfectVector — Espera e requisições assíncronas](https://perfectvector.com/docs/api/waiting-and-async) — Envio assíncrono e consultas de status. 4. [PerfectVector — Resultados](https://perfectvector.com/docs/api/results) — Download, falhas e expiração do resultado. 5. [PerfectVector — Modo de teste](https://perfectvector.com/docs/api/test-mode) — Validações de upload e resultados verificáveis com a chave de teste. 6. [PerfectVector — Erros](https://perfectvector.com/docs/api/errors) — Intervalos de Retry-After, falhas definitivas e uso de uma nova chave. *** [Obtenha uma chave de teste pela página da API do PerfectVector](https://perfectvector.com/pt-BR/api) e faça um teste com três arquivos seus. Confira se cada registro bem-sucedido tem um SVG em disco e se o reinício não reenvia trabalhos concluídos. ## Explore - [Read the HTML article](https://perfectvector.com/pt-BR/blog/batch-vectorize-images-api) - [Conversão em lote PNG2SVG: confira o ZIP baixado](https://perfectvector.com/pt-BR/blog/png2svg-batch-convert.md) - [Como converter uma pasta em SVGs com o Claude Code](https://perfectvector.com/pt-BR/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)