API Recraft per la rimozione dello sfondo: un esempio funzionante

La maggior parte delle API per la rimozione dello sfondo ti obbliga a scegliere un modello generico di editing delle immagini e a guidarlo con un prompt adeguato per ritagliare il soggetto. recraft/remove-background elimina questo passaggio: è un modello dedicato che riceve un URL di immagine e restituisce un PNG trasparente che conserva i dettagli dei bordi al livello di capelli e peli. Nessun prompt, nessun negative prompt, nessun parametro di intensità — solo l'immagine sorgente in ingresso e il ritaglio in uscita.

Questa guida percorre una chiamata completa e testata: la struttura della richiesta, la risposta che riceverai effettivamente e i pattern di livello produttivo che impediscono ai job in batch di bloccarsi a causa di un caso limite (callback, idempotenza, gestione degli errori).

Prerequisiti:

• Ottenere una API key di hiapi dalla tua console
• Python 3.9+ con requests installato (pip install requests), oppure usare direttamente curl
• La tua immagine sorgente deve trovarsi a un URL pubblico — l'API dei task di hiapi recupera le immagini tramite URL, non tramite upload di file. Formato PNG, JPG o WEBP, massimo 5MB, massimo 16 milioni di pixel, entrambe le dimensioni tra 256 e 4096 pixel.

La richiesta

Come tutti i modelli generativi su hiapi, recraft/remove-background funziona tramite l'API asincrona dei task condivisa: POST /v1/tasks con model e input, e ricevi immediatamente un taskId, mentre il ritaglio viene eseguito in background. Il contratto completo — header, chiavi di idempotenza, codici di stato — è documentato in modo uniforme in Creazione di un task; la parte specifica del modello è input, che per questo modello contiene un solo campo:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft/remove-background",
  "input": {
    "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg"
  }
}'

import requests

payload = {
    "model": "recraft/remove-background",
    "input": {
        "image_url": "https://static.hiapi.ai/model-covers/recraft-remove-background/2026/09/01/golden-input-2048.jpg",
    },
}

response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())
# {"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

image_url è l'unico campo accettato da questo modello — non esistono format, response_format o parametri di dimensione. Se invii qualsiasi altra cosa, l'API rifiuta l'intera richiesta con un errore di schema prima ancora di raggiungere il modello (vedi Errori sotto). L'output è sempre un PNG trasparente.

Polling del risultato

Prendi il taskId dalla risposta precedente ed esegui il polling di GET /v1/tasks/{taskId} finché data.status non raggiunge uno stato terminale. L'enumerazione degli stati è coerente tra tutti i modelli della piattaforma: queued → handling → archiving → success (o fail). L'esecuzione effettiva di questo modello di solito termina in meno di 10 secondi:

import time

task_id = response.json()["data"]["taskId"]

while True:
    r = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    data = r.json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

print(data)

Quando lo stato è success, data.output è un array con un solo elemento:

{
  "status": "success",
  "output": [
    {
      "artifactId": "119426",
      "type": "image",
      "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M1RYTHQ5F94S2405YSC65EWM-0.png",
      "expireAt": 1789222580
    }
  ]
}

url è un link temporaneo — expireAt è un timestamp Unix a circa una settimana di distanza, non un indirizzo CDN permanente. Scarica i byte e salvali nel tuo storage non appena il task ha successo:

image_bytes = requests.get(data["output"][0]["url"]).content
with open("cutout.png", "wb") as f:
    f.write(image_bytes)

Pattern di livello produttivo

Usa le callback invece del polling in loop. Passa callback.url al momento della creazione e hiapi invierà il risultato finale via POST quando il task è completato, invece di farti consumare richieste in un loop di polling:

payload = {
    "model": "recraft/remove-background",
    "callback": {"url": "https://example.com/hiapi/callback", "when": "final"},
    "input": {"image_url": "https://your-cdn.example.com/product-01.jpg"},
}

when: "final" significa che riceverai una sola callback, attivata allo stato terminale (success o fail), e non una per ogni stato intermedio. Per un lotto di foto di prodotti è l'impostazione predefinita adeguata: non devi mantenere un loop di polling per ogni immagine.

Idempotenza. Se la richiesta va in timeout dalla tua parte ma è effettivamente arrivata a hiapi, ritentare con lo stesso header Idempotency-Key (documentato in Creazione di un task) restituisce il task originale senza addebitare un secondo ritaglio. Vale la pena impostarlo per qualsiasi job in batch che ritenta in caso di errore di rete.

Errori — due forme, non una. Le richieste malformate e i fallimenti di autenticazione vengono restituiti con envelope diversi; un codice che controlla solo uno dei due ignora silenziosamente l'altro:

// Errore di input (validazione dello schema) — HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// API key non valida o scaduta — HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

Controlla prima error_code, poi passa a error.code — non dare per scontato che tutti i fallimenti abbiano le stesse chiavi di primo livello.

Prezzo. $0.01 per immagine (20 crediti), indipendentemente dalla risoluzione di input, con tariffa uniforme. Il prezzo corrente è sempre sulla pagina dei prezzi.

Quando devi sostituire lo sfondo, non solo ritagliarlo

recraft/remove-background produce solo ritagli trasparenti — nessun riempimento, nessuna scena. Se l'obiettivo è sostituire lo sfondo con uno da studio fotografico o una scena lifestyle nella stessa chiamata, è un altro task: usa un modello image-to-image e istruiscilo a rigenerare lo sfondo attorno al soggetto preservato. Consulta Rimuovere lo sfondo da un'immagine con l'API: editing basato su prompt per capire questo approccio e quando vale la pena pagare più di un semplice ritaglio.

Domande frequenti

recraft/remove-background accetta prompt o parametri di intensità? No. Lo schema è rigido — image_url è l'unico campo accettato. Inviare campi aggiuntivi come format o response_format restituisce un 400 con il messaggio "additional properties not allowed".

Quali formati e dimensioni di immagine sono supportati? Input: PNG, JPG o WEBP, massimo 5MB, massimo 16 milioni di pixel, entrambe le dimensioni tra 256 e 4096 pixel. L'output è sempre un PNG con canale alpha.

Posso caricare un file locale invece di un URL? No — image_url deve essere un URL http(s):// pubblico che i server di hiapi possano recuperare. Carica prima su un object storage o su una CDN.

Quanto dura l'URL di output? Il campo expireAt su ogni voce di output è un timestamp Unix, di solito a circa una settimana di distanza. Trattalo come un link temporaneo e copia i byte nel tuo storage immediatamente dopo il successo del task — non conservare a lungo i link temp.hiapi.ai.

Questo è adatto all'elaborazione in batch di centinaia di foto di prodotti? Sì — invia un task per ogni immagine, condividi un unico callback.url e lascia che hiapi invii i risultati in push, invece di eseguire il polling uno per uno. A $0.01/immagine, elaborare un catalogo di 1.000 immagini costa $10 di generazione.