Как использовать seedream-5.0-pro/image-to-image через hiapi API: curl, Python и рабочий пример запроса

Seedream 5.0 Pro — флагманская модель изображений от ByteDance; её эндпоинт «изображение-в-изображение» (image-to-image) принимает одно или несколько референсных изображений и текстовую инструкцию, а возвращает отредактированный результат: перерисовку стиля, замену фона, очистку продуктовых фото, композицию нескольких изображений. В hiapi она работает поверх единого асинхронного API tasks: вы сначала создаёте задачу, затем опрашиваете её (или принимаете callback), а в конце скачиваете результат. Каждый параметр, значение перечисления и сообщение об ошибке в этом руководстве были сверены с работающим API до публикации.

Что вы создадите и что потребуется

Цель: отправить одно референсное изображение и одну инструкцию редактирования в seedream-5.0-pro/image-to-image, получить отредактированное изображение и сохранить его локально.

Вам понадобятся две вещи:

1. Ключ hiapi API — получите его в консоли. Его нужно поместить в заголовок Authorization: Bearer sk-....
2. Публично доступные URL изображений — API загружает ваши референсные изображения на сервере, поэтому они должны быть доступны по HTTPS. Предподписанные URL из вашего собственного бакета подходят; localhost или приватные пути — нет. Если URL не удаётся загрузить, вы получите нормализованную ошибку, а не тихий сбой.

Параметры (проверены)

ID модели — seedream-5.0-pro/image-to-image, в точности как возвращает GET /v1/models. Все четыре входных поля обязательны:

Поле	Тип	Обязательно	Значения / описание
prompt	string	да	Инструкция редактирования.
image_urls	массив строк	да	1–10 публично доступных URL изображений. Всегда массив, даже если изображение одно.
aspect_ratio	string	да	match_input_image, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
resolution	string	да	1K или 2K

Два места, где легко ошибиться:

• Схема строгая. Неизвестные поля отклоняются: отправка n, size или seed вернёт 400 с additional properties ... not allowed. В hiapi входная схема у каждой модели своя (одни используют size, другие — aspect_ratio), поэтому не копируйте поля между семействами моделей.
• Здесь resolution поддерживает только 1K/2K. Другие эндпоинты seedream принимают иные наборы разрешений, поэтому стоит проверять по эндпоинту, а не предполагать.

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

Создание задачи:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

При успешном создании ID задачи возвращается в data.taskId (ответ упрощён):

{ "data": { "taskId": "<your-task-id>" } }

Опрашивайте, пока задача не достигнет терминального состояния:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status в итоге станет success — URL вашего изображения находится в data.output[0].url — или fail, с подробностями в data.error.code и data.error.message.

Полный скрипт Python: создание, опрос, скачивание

Только стандартная библиотека — ничего устанавливать не нужно:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the edit task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

Замечания для продакшена

На сервере предпочитайте callback, а не опрос. При создании задачи добавьте объект верхнего уровня callback, и hiapi один раз отправит POST на ваш эндпоинт при переходе в терминальное состояние:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

В обработчике воспринимайте callback как сигнал, а не как источник истины: извлеките из него ID задачи, затем сами перезапросите GET /v1/tasks/<id> и действуйте по результату. Для скриптов, ноутбуков и разовых задач опрос по-прежнему подходит — просто держите интервал около 5 секунд.

Сделайте повторные попытки идемпотентными. При создании задачи сохраняйте собственное сопоставление исходное изображение → taskId. Если процесс падает посреди опроса, перепривяжитесь к сохранённому taskId, а не отправляйте редактирование заново — повторная отправка создаст вторую оплачиваемую задачу.

Скачивайте результат сразу. URL в data.output[0].url ограничен по времени (содержит срок истечения). Скачайте байты и сохраните в свой бакет; никогда не используйте URL результата задачи напрямую в пользовательском контенте.

Ошибки, которые вы реально встретите:

• 401 с permission_denied — ключ API отсутствует или имеет неверный формат. Проверьте, что заголовок ровно Authorization: Bearer sk-....
• 400 с INVALID_REQUEST — нарушение входной схемы. Сообщение точное, например resolution: value must be one of '1K', '2K' или image_urls: maxItems: got 11, want 10.
• image_urls must be an array — вы передали голую строку. Даже одно изображение оборачивайте в список.

Что дальше

• Страница модели: seedream-5.0-pro/image-to-image — возможности и текущий статус.
• Цена за изображение указана на странице цен.
• Более дешёвый вариант редактирования для высоконагруженных конвейеров: как использовать seedream-5.0-lite изображение-в-изображение.
• Выбор между моделями: лучшие image-to-image API 2026 года сравнивает одинаковые задачи редактирования на трёх моделях.
• Полная справка по API: документация hiapi.

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

Сколько референсных изображений можно отправить максимум? До 10 URL в image_urls. Ограничение действует на сервере — 11 изображений вернут maxItems: got 11, want 10.

Может ли результат сохранить соотношение сторон входного изображения? Да — установите aspect_ratio в match_input_image. Для редактирования и перерисовки обычно это то, что нужно; явное соотношение вроде 16:9 выбирайте, только если намеренно меняете композицию.

Поддерживает ли seedream-5.0-pro image-to-image 4K? Нет. Этот эндпоинт принимает только 1K и 2K. Если запросить любое другое значение, вернётся 400 со списком допустимых значений.

URL моих изображений обязательно должны быть публичными? Они должны загружаться серверами hiapi по HTTPS. Предподписанные URL (S3, R2, GCS) отлично работают и позволяют держать сам бакет приватным.

Сколько стоит seedream-5.0-pro image-to-image за изображение? Оплата взимается за успешно сгенерированное изображение и зависит от разрешения — актуальные тарифы смотрите на живой странице цен.

Чем это отличается от seedream-5.0-lite image-to-image? Pro — флагманский уровень для более сложных и точных правок; lite — более быстрый и дешёвый вариант для больших объёмов. Структура запроса похожа, поэтому самый ясный способ решить — прогнать одинаковую задачу редактирования на обеих моделях: начните с руководства по lite и сравните результат со своими референсными изображениями.