API de eliminación de fondo de Recraft: un ejemplo funcional

La mayoría de las API de eliminación de fondo requieren que elijas un modelo genérico de edición de imágenes y luego lo guíes con el prompt adecuado para recortar el sujeto. recraft/remove-background elimina ese paso: es un modelo dedicado que recibe una URL de imagen y devuelve un PNG transparente que conserva el detalle de bordes a nivel de cabello y pelaje. Sin prompt, sin prompt negativo, sin parámetro de intensidad: solo la imagen de origen como entrada y el recorte como salida.

Esta guía recorre una llamada completa y probada: la estructura de la petición, la respuesta que realmente recibirás y los patrones de nivel de producción (callbacks, idempotencia, manejo de errores) que evitan que un trabajo por lotes se quede atascado por un caso límite.

Requisitos previos:

• Obtener una clave de API de hiapi desde tu consola
• Python 3.9+ con requests instalado (pip install requests), o usar curl directamente
• Tu imagen de origen debe estar en una URL pública: la API de tareas de hiapi obtiene las imágenes por URL, no mediante carga de archivos. Formato PNG, JPG o WEBP, máximo 5 MB, máximo 16 megapíxeles, con ambas dimensiones entre 256 y 4096 píxeles.

La petición

Como todos los modelos de generación en hiapi, recraft/remove-background funciona a través de la API de tareas asíncrona compartida: POST /v1/tasks con model e input, y recibes de inmediato un taskId mientras el recorte se ejecuta en segundo plano. El contrato completo —cabeceras, claves de idempotencia, códigos de estado— está documentado de forma unificada en Crear una tarea; la parte específica del modelo es input, que para este modelo tiene un único 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 es el único campo que acepta este modelo: no hay format, response_format ni parámetros de tamaño. Si envías cualquier otra cosa, la API rechaza toda la petición con un error de esquema antes de que llegue al modelo (consulta Errores más abajo). La salida es siempre un PNG transparente.

Sondear el resultado

Toma el taskId de la respuesta anterior y consulta GET /v1/tasks/{taskId} hasta que data.status alcance un estado terminal. La enumeración de estados es la misma en todos los modelos de la plataforma: queued → handling → archiving → success (o fail). La ejecución real de este modelo suele completarse en menos de 10 segundos:

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)

Cuando el estado es success, data.output es 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 es un enlace temporal: expireAt es una marca de tiempo Unix de aproximadamente una semana después, no una dirección CDN permanente. Descarga los bytes y guárdalos en tu propio almacenamiento en cuanto la tarea tenga éxito:

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

Patrones de nivel de producción

Usa callbacks en lugar de sondeo en bucle. Pasa callback.url al crear la tarea y hiapi enviará el resultado final por POST cuando la tarea termine, en lugar de hacerte consumir peticiones en un bucle de sondeo:

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 que solo recibirás un callback, disparado en el estado terminal (success o fail), en lugar de uno por cada estado intermedio. Para un lote de fotos de producto, esta es la configuración predeterminada adecuada: no tienes que mantener un bucle de sondeo por cada imagen.

Idempotencia. Si la petición se agota en tu lado pero en realidad ya llegó a hiapi, reintentar con la misma cabecera Idempotency-Key (documentada en Crear una tarea) devuelve la tarea original en lugar de cobrarte un segundo recorte. Conviene configurarla en cualquier trabajo por lotes que reintente ante errores de red.

Errores: dos formas, no una. Las peticiones mal formadas y los fallos de autenticación se devuelven con sobres distintos, y el código que solo comprueba uno de ellos se traga silenciosamente el otro:

// Error de entrada (validación de esquema) — HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// Clave de API no válida o caducada — HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

Comprueba primero error_code y recurre después a error.code: no asumas que todos los fallos tienen las mismas claves de nivel superior.

Precios. 0,01 $ por imagen (20 créditos), con precio uniforme independientemente de la resolución de entrada. Los precios actuales están siempre en la página de precios.

Cuando necesitas sustituir el fondo, no solo recortarlo

recraft/remove-background solo genera un recorte transparente: no rellena ni añade escena. Si el objetivo es cambiar a un fondo de estudio o una escena de estilo de vida en la misma llamada, esa es otra tarea: usa un modelo de imagen a imagen y pídele que regenere el fondo alrededor del sujeto conservado. Consulta Eliminar el fondo de una imagen con la API: edición basada en prompts para conocer ese método y cuándo merece la pena pagar más que por un simple recorte.

Preguntas frecuentes

¿recraft/remove-background acepta prompts o parámetros de intensidad? No. El esquema es estricto: image_url es el único campo aceptado. Enviar campos adicionales como format o response_format devuelve un 400 con el mensaje "additional properties not allowed".

¿Qué formatos y tamaños de imagen se admiten? Entrada: PNG, JPG o WEBP, máximo 5 MB, máximo 16 megapíxeles, con ambas dimensiones entre 256 y 4096 píxeles. La salida es siempre un PNG con canal alfa.

¿Puedo subir un archivo local en lugar de una URL? No: image_url debe ser una URL http(s):// pública que los servidores de hiapi puedan obtener. Súbela primero a un almacenamiento de objetos o a una CDN.

¿Cuánto tiempo es válida la URL de salida? El campo expireAt de cada elemento de salida es una marca de tiempo Unix, normalmente de aproximadamente una semana después. Trátala como un enlace temporal y copia los bytes a tu propio almacenamiento en cuanto la tarea tenga éxito: no guardes enlaces de temp.hiapi.ai a largo plazo.

¿Sirve para procesar por lotes cientos de fotos de producto? Sí: envía una tarea por imagen, comparte un único callback.url y deja que hiapi envíe los resultados, en lugar de sondear uno a uno. A 0,01 $ por imagen, procesar un catálogo de 1.000 imágenes cuesta 10 $ en generación.