Как использовать bria-product-shot через API hiapi: curl, Python и один рабочий запрос

bria-product-shot принимает фотографию продукта и возвращает новое изображение, помещающее продукт в другую сцену. Вы можете описать сцену на английском языке или предоставить эталонное изображение, чтобы результат следовал стилю фона этого изображения. В этом руководстве показан запрос, полностью отработанный на hiapi, а также правила параметров, определяющие, будет ли запрос принят.

Вам понадобится ключ API hiapi со страницы API Keys в панели управления, а также общедоступный URL фотографии продукта (JPEG, PNG или WEBP, максимум 12 МБ).

Минимальный рабочий пример (curl)

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bria-product-shot",
    "input": {
      "image_url": "https://your-cdn.example.com/serum-bottle.png",
      "prompt": "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
      "placement_type": "manual_placement",
      "manual_placement_selection": "bottom_center"
    }
  }'

Запрос на создание сразу возвращает ID задачи:

{"code":200,"data":{"taskId":"tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW"},"message":"success"}

Опрашивайте GET /v1/tasks/<taskId>, пока data.status не станет success или fail. Ответ по завершении выглядит так (имя хоста вывода сокращено):

{
  "code": 200,
  "data": {
    "model": "bria-product-shot",
    "status": "success",
    "storage": "temp",
    "taskId": "tk-hiapi-01M5K7TWWMM68ZDTERJN4QV8MW",
    "output": [{"artifactId": "287064", "type": "image", "expireAt": 1793325686,
                "url": "https://temp.hiapi.ai/.../...-0.png"}]
  },
  "message": "success"
}

Версия на Python

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def product_shot(image_url: str, scene: str, position: str = "bottom_center") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "bria-product-shot",
        "input": {
            "image_url": image_url,
            "prompt": scene,
            "placement_type": "manual_placement",
            "manual_placement_selection": position,
        },
    }, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    for _ in range(60):
        d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d["status"] == "success":
            # output URLs expire (about 7 days): download immediately
            return requests.get(d["output"][0]["url"], timeout=60).content
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

open("shot.png", "wb").write(product_shot(
    "https://your-cdn.example.com/serum-bottle.png",
    "On a white marble countertop beside a window, soft morning light, a few green leaves in the background",
))

Ключевые параметры

Поле	Описание
image_url	Обязательно. Публичный http(s) URL фотографии продукта.
prompt	Описание сцены на английском языке, от 1 до 1000 символов.
reference_image_url	Эталонное изображение сцены. Используйте этот параметр или prompt — только один из них, ни в коем случае не оба одновременно.
placement_type	manual_placement (по умолчанию) размещает продукт в заданной позиции; original сохраняет его положение на фотографии.
manual_placement_selection	bottom_center (по умолчанию), upper_left, upper_right, bottom_left, bottom_right, right_center, left_center, upper_center, center_vertical, center_horizontal. Действует только при использовании manual_placement.
original_quality	Действует только при использовании original: сохраняет размер входного изображения вместо масштабирования примерно до 1 MP.
fast	По умолчанию true. Отключите, чтобы использовать стандартную модель; цена та же.
optimize_description	По умолчанию true. Расширяет текст сцены; действует только при использовании prompt и не может использоваться вместе с эталонным изображением.

Схема закрытая (additionalProperties: false) и содержит межполевые правила, поэтому комбинации prompt плюс reference_image_url или original плюс заданная позиция являются недопустимыми запросами.

Записи тестирования и замечания

Что было выполнено на живом API:

• С указанным выше запросом была выполнена одна реальная генерация, fast оставлен по умолчанию. Задача прошла через handling и archiving и достигла success примерно через 26 секунд после создания.
• Для квадратного входа выходные данные — PNG 1024×1024 (около 1 МБ), что соответствует описанию на странице модели: для квадратного входа заданные позиции измеряются в 1024×1024.
• Намеренно заданное неверное значение "manual_placement_selection": "middle" было отклонено при создании с HTTP 400 и error_code: INVALID_REQUEST. Сообщение об ошибке перечисляет все десять допустимых позиций, поэтому вы можете сразу показать его пользователю, не дожидаясь сбоя задачи.

Практические советы:

• Скачивайте выходные данные немедленно. Каждый результат содержит метку времени expireAt (время Unix после завершения, около семи дней); сохраняйте изображения в собственное хранилище.
• Фиксированная цена за изображение. Согласно странице модели, текст сцены и эталонное изображение, позиция размещения и быстрый режим не меняют цену. Смотрите актуальные цифры на странице цен, а не жёстко прописывайте их в коде.
• В этом руководстве была выполнена только одна генерация, поэтому страница не делает никаких заявлений о качестве для разных категорий продуктов. Перед массовым использованием протестируйте изображения собственного каталога.

Рекомендации для продакшена

• Создайте задачу, сохраните taskId и при временных сетевых ошибках повторяйте опрос несколько раз. Опрашивайте сохранённый id, а не создавайте новую задачу, поскольку новая задача будет снова тарифицирована.
• Для очередей проверяйте manual_placement_selection на клиенте по десяти значениям выше, чтобы ошибочные входные данные никогда не доходили до API.

Связанные страницы

• Страница модели Bria Product Shot: актуальные цены, форма ввода и песочница.
• Страница модели Bria Eraser: удаление объектов с помощью маски — это другая задача, отличная от помещения продукта в новую сцену.
• Просмотреть все модели изображений
• Руководство по API удаления фона 851-labs: если фон исходной фотографии загромождён, сначала вырежьте продукт.
• Как использовать API изображение-в-изображение FLUX.2

Часто задаваемые вопросы

Могу ли я использовать эталонное изображение вместо текстового промпта? Да. Отправьте reference_image_url и опустите prompt. Не отправляйте оба одновременно и не отправляйте optimize_description вместе с эталонным изображением.

Сколько изображений возвращает один вызов? Одно. Страница модели указывает, что каждый запуск выводит одно изображение.

Останется ли продукт на том же месте, что и на моей фотографии? Только при placement_type: "original". По умолчанию manual_placement перемещает его в выбранную заданную позицию.