Language: EN
Start free

Bulk product photos with one script

This Python script sends a whole folder of product photos through one Herofab tool: it uploads each photo, creates batches of up to 100 jobs, waits for them and saves every finished image under the photo's own name. A ledger file keeps the job ids, so running it again only processes new photos and never pays twice.

  • Python 3.9+ and requests
  • Batches of 100 jobs
  • Safe to run again
How it works

Four steps, all from the public API

Upload

Each photo goes to POST /api/v1/assets as multipart form data (JPEG, PNG or WebP, up to 25 MB). A photo the checks refuse is skipped with the reason.

Batch

Up to 100 uploads become one POST /api/v1/batches request. It is all or nothing: if the credits do not cover every job, no job is created and the script stops.

Wait

GET /api/v1/batches/{id} reports done when no job is left running. A batch.completed webhook can replace the polling loop.

Save

Each succeeded job's image is downloaded and saved with the photo's file name; a failed job prints its failure code and its credits are returned.

Script

herofab_bulk.py

Change TOOL, ROLE and PARAMS to use another tool; each API reference page lists the role and the settings. The Idempotency-Key is a hash of the batch body, so a repeated request returns the batch that already exists instead of a second one.

"""Herofab bulk product photos: a folder of product photos in, one finished image per photo out.

pip install requests
HEROFAB_API_KEY=hf_sk_live_... python herofab_bulk.py ./photos ./results
"""
import hashlib, json, os, pathlib, sys, time
import requests

API = "https://app.herofab.app/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['HEROFAB_API_KEY']}"}
TOOL, ROLE = "ghost_mannequin", "garment"          # the tool and its required input role
PARAMS = {"style": "3d", "backdrop": "white", "aspect_ratio": "1:1"}
CHUNK = 100                                         # POST /batches takes up to 100 jobs

def call(method, path, headers=None, **kw):
    """One API call; waits on 429 (rate limit) and 503 (upload slot busy) as Retry-After says."""
    while True:
        r = requests.request(method, API + path, headers={**AUTH, **(headers or {})}, timeout=120, **kw)
        if r.status_code not in (429, 503):
            return r
        time.sleep(int(r.headers.get("Retry-After", "5")))

src, out = pathlib.Path(sys.argv[1]), pathlib.Path(sys.argv[2])
out.mkdir(exist_ok=True)
ledger = out / "herofab-jobs.json"                  # photo name -> job id: a re-run never pays twice
state = json.loads(ledger.read_text()) if ledger.exists() else {"jobs": {}, "batches": []}
photos = [p for p in sorted(src.iterdir()) if p.suffix.lower() in (".jpg", ".jpeg", ".png", ".webp")]
todo = [p for p in photos if p.name not in state["jobs"]]

for start in range(0, len(todo), CHUNK):
    items, names = [], []
    for photo in todo[start:start + CHUNK]:
        r = call("POST", "/assets", files={"file": (photo.name, photo.read_bytes())})
        asset = r.json()
        if r.status_code != 201 or asset.get("state") != "stored":
            print(f"skipped {photo.name}: {asset.get('rejection') or asset.get('error')}")
            continue
        items.append({"inputs": {ROLE: asset["id"]}, "params": PARAMS})
        names.append(photo.name)
    if not items:
        continue
    body = {"tool": TOOL, "items": items}
    key = hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()  # same body, same key
    r = call("POST", "/batches", json=body, headers={"Idempotency-Key": key})
    if r.status_code >= 400:
        sys.exit(r.json()["error"])                 # e.g. insufficient_credit: nothing was reserved
    batch = r.json()
    for name, job in zip(names, batch["jobs"]):     # jobs come back in item order
        state["jobs"][name] = job["id"]
    state["batches"].append(batch["id"])
    ledger.write_text(json.dumps(state, indent=1))
    print(f"batch {batch['id']}: {batch['total']} jobs, {batch['credits_reserved']} credits held")

names = {job_id: name for name, job_id in state["jobs"].items()}
for batch_id in state["batches"]:
    while not (batch := call("GET", f"/batches/{batch_id}").json())["done"]:
        time.sleep(10)
    for job in batch["jobs"]:
        name = pathlib.Path(names.get(job["id"], job["id"])).stem
        if job["state"] != "succeeded":
            print(f"{name}: {job['failure']['code']} (credits returned)")
            continue
        output = job["outputs"][0]
        target = out / f"{name}.{output['content_type'].split('/')[1]}"
        if not target.exists():
            target.write_bytes(call("GET", f"/assets/{output['asset_id']}/content").content)
ZIP

Or download a batch as one ZIP, sized for a marketplace

GET /api/v1/batches/{id}/outputs.zip streams every finished image of a batch. platform fits each image to a channel's size without cropping and at no extra credit; format=jpg converts them to JPEG.

# Every finished image of one batch in a single ZIP, fitted to Amazon's 1,600 × 1,600 px and converted to JPEG
curl -L "https://app.herofab.app/api/v1/batches/BATCH_ID/outputs.zip?platform=amazon&format=jpg" \
  -H "Authorization: Bearer $HEROFAB_API_KEY" -o amazon.zip
platformChannelSize (px)
amazonAmazon1,600 × 1,600
amazon_clothingAmazon (clothing)1,500 × 2,000
walmartWalmart2,200 × 2,200
ebayeBay1,600 × 1,600
etsyEtsy2,000 × 2,000
shopifyShopify2,048 × 2,048
google_shoppingGoogle Shopping1,500 × 1,500
tiktok_shopTikTok Shop1,600 × 1,600
mercado_livreMercado Livre1,200 × 1,200
shopeeShopee1,600 × 1,600
wayfairWayfair2,000 × 2,000
faireFaire2,000 × 2,000
faire_apparelFaire (clothing)1,800 × 2,400
zalandoZalando1,801 × 2,600
about_youABOUT YOU1,500 × 2,000
ottoOTTO2,000 × 2,000
kauflandKaufland2,048 × 2,048
bolbol2,000 × 2,000
galaxusGalaxus2,000 × 2,000
trendyolTrendyol1,200 × 1,800

Sizes: packages/tools/platforms.json, each with the channel's official source on its marketplace guide. Batch, ZIP and limit details: Herofab OpenAPI document, read 3 November 2026.

Questions

Bulk script questions

How many photos can one request take?

A batch takes up to 100 jobs; the script splits a larger folder into several batches. vary is the other batch form: one photo, one setting with 2 to 10 values, one job per value.

What does a batch of 100 cost?

100 times the tool's credits, held when the batch is created and charged per delivered image; failed jobs return their credits. The ghost mannequin settings in the script cost 4 credits per image.

Does it upload in parallel?

No. Multipart uploads are taken one at a time per workspace and a second one gets 503 with Retry-After, which the script waits out. For very large files, the upload intent form of POST /api/v1/assets sends the bytes straight to storage.

Related
Get started

Your next collection, shot this week.

20 credits at sign-up, no card required. Images made with free credits carry a watermark. Herofab also removes the watermark from those images once credits are purchased.