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

# Como vetorizar uma imagem em Python com uma API

> Envie um PNG, JPEG ou WebP a uma API de vetorização pelo Python. Salve o SVG, verifique a resposta de teste e recupere a conversão se a conexão cair.

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

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

Um script Python pode enviar uma imagem rasterizada à API do PerfectVector e salvar o SVG ao lado do original. O exemplo mostra o ID de conversão antes de baixar o arquivo. Se a conexão cair, você pode recuperar o resultado usando o ID ou a chave da requisição que escolheu.

## Prepare uma chave de teste e uma imagem

Crie uma chave de teste pela [página da API para desenvolvedores](https://perfectvector.com/account/developers). Defina a chave no terminal como `PERFECTVECTOR_API_KEY` e mantenha-a fora do script e do controle de versão. Instale o Requests no ambiente Python do projeto com `python -m pip install requests`.

No primeiro teste, use um PNG, JPEG ou WebP de quadro único, como um logo de 512 × 512 pixels chamado `logo.png`. A API aceita arquivos de até 5 MiB e imagens com 100 a 4096 pixels de cada lado. O modo de teste valida o envio e retorna sem cobrança um SVG fixo marcado como “TEST MODE”. O arquivo permite verificar a requisição e o download. Para avaliar a qualidade do traçado da sua imagem, faça uma conversão em produção. [Modo de teste da API do PerfectVector](https://perfectvector.com/docs/api/test-mode)

Executamos o script com uma chave de teste, baixamos um SVG válido e repetimos o upload com a mesma chave de requisição. As duas execuções retornaram o mesmo ID de conversão.

**Diagrama do fluxo**

![Um arquivo rasterizado local segue em uma requisição identificada para um serviço na nuvem e volta como um arquivo vetorial em disco.](https://perfectvector.com/blog/vectorize-image-python-api/workflow.webp)

*Guarde a chave junto com o envio e salve o ID de conversão antes de baixar o SVG.*

## Envie a imagem e salve o SVG em Python

Salve o código abaixo como `vectorize.py`. O argumento `files` faz o Requests montar um upload multipart com os dados originais no campo `image`. [Uploads multipart com 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])
```

Execute a partir do diretório que contém `logo.png`. Escolha um identificador para a conversão e anote-o antes de rodar o comando. A API chama esse valor de *chave de idempotência*. Ele associa repetições de um mesmo envio a uma única conversão. O exemplo usa `logo-asset-0001`. Use outro valor para outra imagem ou operação. [Repetições seguras no PerfectVector](https://perfectvector.com/docs/api/idempotency)

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

Um teste bem-sucedido mostra o ID de conversão e a contagem de bytes e salva `logo.svg` ao lado de `logo.png`. Abra `logo.svg` para confirmar que o exemplo aparece. O script substitui um SVG com o mesmo nome depois que baixa o arquivo novo. Use uma pasta temporária no primeiro teste.

O script pede ao servidor que espere até 10 segundos antes de retornar uma conversão inacabada. Ele consulta os estados `queued` e `processing` a cada dois segundos, em média, e só baixa o resultado quando o status chega a `succeeded`. Conversões de teste terminam na hora. Simule uma resposta pendente em um teste local para verificar essa etapa antes de usá-la em produção. [Espera e requisições assíncronas no PerfectVector](https://perfectvector.com/docs/api/waiting-and-async)

## Recupere uma conversão após o tempo limite

Se o Python exibiu um ID, consulte-o com `GET /v1/vectorizations/{id}`. Quando a conversão terminar com sucesso, use `GET /v1/vectorizations/{id}/result` na mesma conta e modo para baixar o SVG. Os links expiram 24 horas após o término. Copie o arquivo para seu próprio armazenamento se precisar dele mais tarde. [Downloads de resultados do PerfectVector](https://perfectvector.com/docs/api/results)

Se o Python parou antes de exibir o ID, execute o comando de novo com os mesmos dados e a mesma chave de idempotência em até 24 horas da primeira requisição. A API retorna a conversão existente se aceitou o primeiro envio. Após esse prazo, um envio com a mesma chave pode iniciar outra conversão. [Repetições seguras no PerfectVector](https://perfectvector.com/docs/api/idempotency)

| O que aparece                                       | O que conferir                                                                                                                      |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `401 invalid_api_key`                               | Configure uma chave de teste válida no ambiente que o Python usa. Se revogou a chave, crie outra no mesmo modo.                     |
| `415 unsupported_media_type` ou `422 invalid_image` | Abra o original e confira o formato real e as dimensões em pixels. Salve uma imagem corrigida e dê uma chave própria a esse envio.  |
| Um ID de conversão seguido de `processing_failed`   | A API criou o registro, mas não conseguiu vetorizar a imagem. Examine o original e reenvie um arquivo corrigido como nova operação. |
| `409 idempotency_conflict`                          | A mesma chave foi usada com outros dados ou opções. Recupere com o original ou dê uma nova chave à nova entrada.                    |

Se precisar falar com o suporte, guarde o ID da requisição na exceção ou o ID de conversão exibido pelo script. A [referência de erros da API](https://perfectvector.com/docs/api/errors) indica quando é seguro tentar de novo.

## Perguntas frequentes

### O mesmo script Python vetoriza JPEG ou WebP?

Sim. Passe o JPEG ou WebP como primeiro argumento. Valem as mesmas regras de tamanho, dimensões e quadro único. A saída usa a extensão SVG.

### Posso usar esse exemplo em Python para uma pasta inteira?

Primeiro, verifique um upload e um download. Para uma pasta, guarde a chave, o ID de conversão e o caminho de saída de cada arquivo em uma fila persistente. Por padrão, o PerfectVector permite uma conversão em produção por vez em cada conta. Espere o fim de cada uma antes de enviar a próxima. [Limites da API do PerfectVector](https://perfectvector.com/docs/api/limits)

## Fontes

1. [Requests — Início rápido](https://requests.readthedocs.io/en/latest/user/quickstart/) — Arquivos multipart, tempos limite e respostas binárias.
2. [PerfectVector — Modo de teste](https://perfectvector.com/docs/api/test-mode) — Limites de upload, SVG fixo e créditos em modo de teste.
3. [PerfectVector — Espera e requisições assíncronas](https://perfectvector.com/docs/api/waiting-and-async) — Preferência de espera, consultas de status e conclusão de pedidos de teste.
4. [PerfectVector — Idempotência](https://perfectvector.com/docs/api/idempotency) — Prazo, escopo, conflitos e regras de repetição da chave.
5. [PerfectVector — Resultados](https://perfectvector.com/docs/api/results) — Endpoint, autenticação e validade.
6. [PerfectVector — Erros](https://perfectvector.com/docs/api/errors) — Códigos de erro HTTP e instruções para recuperação.
7. [PerfectVector — Limites](https://perfectvector.com/docs/api/limits) — Simultaneidade em produção e limites de arquivo.

***

[Obtenha uma chave de teste na página da API do PerfectVector](https://perfectvector.com/pt-BR/api) e execute o script com uma imagem sua. Confirme que o SVG salvo abre e que o terminal mostra o ID de conversão.

## Explore

- [Read the HTML article](https://perfectvector.com/pt-BR/blog/vectorize-image-python-api)
- [Melhores vetorizadores com IA em 2026: escolhas por uso](https://perfectvector.com/pt-BR/blog/best-ai-vectorizers-2026.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)