Recraft API для удаления фона: рабочий пример

Большинство API для удаления фона требуют выбрать универсальную модель редактирования изображений и затем подсказками направить её на выделение объекта. recraft/remove-background избавляет от этого шага: это специализированная модель, которая принимает URL изображения и возвращает прозрачный PNG с сохранением деталей краёв вплоть до отдельных волос и шерсти. Ни подсказок, ни негативных подсказок, ни параметров силы — только исходное изображение на входе и вырезанный объект на выходе.

Это руководство проводит через один полный, проверенный вызов: структуру запроса, ответ, который вы реально получите, и производственные паттерны (callback, идемпотентность, обработка ошибок), которые не дадут пакетным задачам застрять из-за какого-нибудь граничного случая.

Предварительные требования:

• Получите API-ключ hiapi из вашей консоли
• Python 3.9+ с установленным requests (pip install requests) или используйте curl напрямую
• Ваше исходное изображение доступно по публичному URL — task API hiapi получает изображения по URL, а не через загрузку файлов. Формат PNG, JPG или WEBP, максимум 5MB, максимум 16 миллионов пикселей, оба измерения от 256 до 4096 пикселей.

Запрос

Как и все генеративные модели на hiapi, recraft/remove-background работает через общий асинхронный task API: POST /v1/tasks с model и input, и вы сразу получаете taskId, а вырезание выполняется в фоне. Полный контракт — заголовки, ключи идемпотентности, коды состояния — единообразно описан в разделе Создание задачи; часть, относящаяся к модели, — это input, и для этой модели в нём только одно поле:

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 — единственное поле, которое принимает эта модель: нет ни format, ни response_format, ни параметров размера. Если отправить что-то ещё, API отклонит весь запрос ошибкой схемы ещё до обращения к модели (см. Ошибки ниже). Результат всегда — прозрачный PNG.

Опрос результата

Возьмите taskId из ответа выше и опрашивайте GET /v1/tasks/{taskId}, пока data.status не достигнет терминального состояния. Перечисление статусов одинаково для всех моделей платформы: queued → handling → archiving → success (или fail). Фактическая работа этой модели обычно завершается менее чем за 10 секунд:

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)

При статусе success поле data.output — это массив из одного элемента:

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

url — временная ссылка: expireAt — это Unix-временная метка примерно через неделю, а не постоянный адрес CDN. Скачайте байты и сохраните в собственное хранилище сразу после успеха задачи:

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

Производственные паттерны

Используйте callback вместо цикла опроса. Передайте callback.url при создании, и hiapi отправит вам финальный результат по POST по завершении задачи, вместо того чтобы вы тратили запросы в цикле опроса:

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" означает, что вы получите только один callback, срабатывающий в терминальном состоянии (success или fail), а не по одному на каждое промежуточное состояние. Для партии фотографий товаров это подходящая настройка по умолчанию — вам не нужно поддерживать цикл опроса для каждого изображения.

Идемпотентность. Если запрос у вас истёк по таймауту, но фактически дошёл до hiapi, повтор с тем же заголовком Idempotency-Key (описан в Создании задачи) вернёт исходную задачу и не спишет плату за второе вырезание. Это стоит настроить для любой пакетной задачи, которая повторяет запросы при сетевых ошибках.

Ошибки — два формата, а не один. Запросы с неверным форматом и сбои аутентификации возвращаются в разных конвертах, и код, проверяющий только один из них, молча проглотит другой:

// Ошибка ввода (валидация схемы) — HTTP 400
{"code": 400, "data": null, "error_code": "INVALID_REQUEST", "message": "invalid input: image_url: missing required field \"image_url\""}

// API-ключ недействителен или истёк — HTTP 401
{"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}

Сначала проверяйте error_code, затем переходите к error.code — не предполагайте, что у всех сбоев одинаковые ключи верхнего уровня.

Цены. $0.01 за изображение (20 credits) независимо от разрешения входного изображения, единая цена. Актуальные цены всегда на странице тарифов.

Когда нужно заменить фон, а не просто вырезать объект

recraft/remove-background создаёт только прозрачное вырезание — без заполнения и без сцены. Если цель — заменить фон на студийный или жизненный сценарий в том же вызове, это другая задача: используйте модель image-to-image и подскажите ей заново сгенерировать фон вокруг сохранённого объекта. См. Удаление фона изображения через API: редактирование по подсказкам, чтобы узнать об этом методе и о том, когда стоит платить за него больше, чем за обычное вырезание.

Частые вопросы

Принимает ли recraft/remove-background подсказки или параметры силы? Нет. Схема строгая — image_url единственное принимаемое поле. Отправка лишних полей вроде format или response_format вернёт 400 с сообщением "additional properties not allowed".

Какие форматы и размеры изображений поддерживаются? Вход: PNG, JPG или WEBP, максимум 5MB, максимум 16 миллионов пикселей, оба измерения от 256 до 4096 пикселей. Выход всегда PNG с альфа-каналом.

Можно ли загрузить локальный файл вместо URL? Нет — image_url должен быть публичным http(s):// URL, доступным серверам hiapi. Сначала загрузите файл в объектное хранилище или CDN.

Сколько действует выходной URL? Поле expireAt в каждой записи вывода — это Unix-временная метка, обычно примерно через неделю. Считайте это временной ссылкой и копируйте байты в собственное хранилище сразу после успеха задачи — не сохраняйте ссылки temp.hiapi.ai надолго.

Подходит ли это для пакетной обработки сотен фотографий товаров? Да — отправляйте одну задачу на изображение с общим callback.url, и hiapi будет присылать результаты обратно, вместо опроса каждого по отдельности. При цене $0.01 за изображение обработка каталога из 1 000 изображений обойдётся в $10 на генерацию.