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

# Vektorisasi Gambar di Python dengan API

> Kirim PNG, JPEG, atau WebP ke API vektorisasi dengan Python. Simpan SVG, cek respons uji, dan pulihkan konversi yang sama jika koneksi putus.

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

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

Skrip Python bisa mengirim gambar raster ke API vektorisasi PerfectVector dan menyimpan SVG di samping berkas aslinya. Contoh berikut mencetak ID konversi sebelum mengunduh hasil. Jika koneksi putus, ID tersebut dan kunci permintaan yang Anda pilih memberi dua cara untuk mengambil kembali hasilnya.

## Siapkan kunci uji dan satu gambar

Buat kunci uji di [halaman Developer API](https://perfectvector.com/account/developers). Atur sebagai variabel lingkungan `PERFECTVECTOR_API_KEY` di terminal. Jangan masukkan kunci ke skrip atau kontrol versi. Pasang Requests di lingkungan Python proyek dengan `python -m pip install requests`.

Untuk uji pertama, gunakan PNG, JPEG, atau WebP satu bingkai, misalnya logo berukuran 512 × 512 bernama `logo.png`. API menerima berkas hingga 5 MiB dengan lebar dan tinggi masing-masing 100 hingga 4096 piksel. Mode uji memeriksa unggahan lalu mengembalikan SVG tetap bertuliskan “TEST MODE” tanpa biaya. Berkas itu memeriksa permintaan dan unduhan. Untuk menilai kualitas vektorisasi gambar Anda, gunakan konversi live. [Mode uji API PerfectVector](https://perfectvector.com/docs/api/test-mode)

Kami menjalankan skrip dengan kunci uji, mengunduh SVG yang berhasil dibaca oleh parser, lalu mengirim ulang unggahan yang sama dengan kunci permintaan yang sama. Kedua proses mengembalikan ID konversi yang sama.

**Ilustrasi alur kerja**

![Berkas raster lokal dikirim ke layanan cloud bersama kunci permintaan, lalu kembali sebagai berkas vektor di penyimpanan lokal.](https://perfectvector.com/blog/vectorize-image-python-api/workflow.webp)

*Simpan kunci bersama catatan unggahan dan catat ID konversi sebelum mengunduh SVG.*

## Kirim gambar dan simpan SVG dengan Python

Simpan kode ini sebagai `vectorize.py`. Argumen `files` membuat Requests membangun unggahan multipart dengan byte asli di kolom formulir `image`. [Unggahan multipart dengan 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])
```

Jalankan dari folder yang berisi `logo.png`. Tentukan ID untuk konversi ini dan catat sebelum menjalankan perintah. API menyebutnya *kunci idempotensi*, yaitu nilai yang mengaitkan pengiriman ulang unggahan yang sama dengan satu konversi. Contoh ini memakai `logo-asset-0001`. Gunakan nilai berbeda untuk gambar atau operasi lain. [Cara aman mengulangi permintaan](https://perfectvector.com/docs/api/idempotency)

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

Jika uji berhasil, skrip mencetak ID konversi dan jumlah byte, lalu membuat `logo.svg` di samping `logo.png`. Buka `logo.svg` untuk memastikan contohnya tampil. Skrip mengganti SVG bernama sama setelah berkas baru diunduh. Gunakan folder sementara saat mencoba pertama kali.

Skrip meminta server menunggu hingga 10 detik sebelum mengembalikan konversi yang belum selesai. Skrip mengecek status `queued` dan `processing` sekitar setiap dua detik, dan hanya mengunduh saat statusnya `succeeded`. Konversi uji langsung selesai. Sebelum mengandalkan skrip ini dalam mode live, gunakan respons lokal yang belum selesai untuk menguji bagian pengecekan status. [Waktu tunggu dan proses asinkron PerfectVector](https://perfectvector.com/docs/api/waiting-and-async)

## Pulihkan konversi setelah batas waktu habis

Jika Python sudah mencetak ID, cek ID itu dengan `GET /v1/vectorizations/{id}`. Setelah berhasil, unduh SVG dengan `GET /v1/vectorizations/{id}/result` di akun dan mode yang sama. Tautan hasil kedaluwarsa 24 jam setelah konversi selesai. Simpan salinan jika Anda membutuhkannya nanti. [Unduhan hasil PerfectVector](https://perfectvector.com/docs/api/results)

Jika Python berhenti sebelum mencetak ID, ulangi perintah dengan byte berkas dan kunci idempotensi yang sama dalam 24 jam sejak permintaan pertama. Jika permintaan awal diterima, API mengembalikan konversi yang sudah ada. Setelah jangka itu, pengiriman dengan kunci yang sama bisa memulai konversi baru. [Cara aman mengulangi permintaan](https://perfectvector.com/docs/api/idempotency)

| Pesan                                                 | Yang perlu diperiksa                                                                                                                                    |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 invalid_api_key`                                 | Atur kunci uji yang berlaku di lingkungan Python. Jika kunci lama sudah dicabut, buat pengganti pada mode yang sama.                                    |
| `415 unsupported_media_type` atau `422 invalid_image` | Buka berkas asli dan periksa format serta dimensinya. Simpan berkas yang sudah diperbaiki dan unggah dengan kunci baru.                                 |
| ID konversi diikuti `processing_failed`               | API telah mencatat konversi, tetapi gambar tidak bisa divektorisasi. Periksa berkas asli, lalu kirim berkas yang telah diperbaiki sebagai operasi baru. |
| `409 idempotency_conflict`                            | Kunci yang sama dipakai dengan byte atau opsi berbeda. Gunakan berkas asli untuk pemulihan atau beri masukan baru kunci baru.                           |

Jika perlu menghubungi dukungan, simpan ID permintaan yang muncul dalam pesan kesalahan atau ID konversi yang dicetak skrip. [Panduan kesalahan API](https://perfectvector.com/docs/api/errors) menjelaskan permintaan mana yang aman diulang.

## Pertanyaan umum

### Bisakah skrip Python yang sama mengonversi JPEG atau WebP?

Bisa. Berikan JPEG atau WebP sebagai argumen pertama. Batas ukuran dan dimensi serta syarat satu bingkai tetap berlaku. Berkas keluaran berekstensi SVG.

### Bisakah contoh Python ini dipakai untuk satu folder?

Uji dulu satu unggahan dan unduhan. Untuk satu folder, catat kunci, ID konversi, dan jalur keluaran setiap berkas dalam antrean yang tetap tersimpan setelah proses berhenti. Secara bawaan, PerfectVector mengizinkan satu konversi live sekaligus per akun. Tunggu sampai selesai sebelum mengirim gambar berikutnya. [Batas API PerfectVector](https://perfectvector.com/docs/api/limits)

## Sumber

1. [Requests — Panduan singkat](https://requests.readthedocs.io/en/latest/user/quickstart/) — Berkas multipart, batas waktu, dan respons byte.
2. [PerfectVector — Mode uji](https://perfectvector.com/docs/api/test-mode) — Batas unggahan, SVG contoh, dan pemakaian kredit saat pengujian.
3. [PerfectVector — Waktu tunggu dan proses asinkron](https://perfectvector.com/docs/api/waiting-and-async) — Waktu tunggu server, pengecekan status, dan penyelesaian permintaan uji.
4. [PerfectVector — Idempotensi](https://perfectvector.com/docs/api/idempotency) — Masa berlaku dan cakupan kunci, konflik, serta pengiriman ulang.
5. [PerfectVector — Hasil](https://perfectvector.com/docs/api/results) — Endpoint hasil, autentikasi, dan kedaluwarsa.
6. [PerfectVector — Kesalahan](https://perfectvector.com/docs/api/errors) — Kode kesalahan HTTP dan pemulihan.
7. [PerfectVector — Batas](https://perfectvector.com/docs/api/limits) — Batas konversi live bersamaan dan batasan berkas.

***

[Ambil kunci uji melalui halaman API PerfectVector](https://perfectvector.com/id/api), jalankan skrip dengan gambar Anda, lalu pastikan SVG dapat dibuka dan terminal mencetak ID konversinya.

## Explore

- [Read the HTML article](https://perfectvector.com/id/blog/vectorize-image-python-api)
- [Alat Vektorisasi Gambar AI Terbaik 2026: Pilihan per Kebutuhan](https://perfectvector.com/id/blog/best-ai-vectorizers-2026.md)
- [Rencanakan Konversi Satu Folder ke SVG di Claude Code](https://perfectvector.com/id/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)