Как использовать seedream-4.5/image-to-image через hiapi API: curl, Python и доступные запросы

Чтобы отредактировать изображение с помощью seedream-4.5, достаточно отправить один POST в единый task API hiapi, сделать короткий опрос статуса и скачать результат. В этом руководстве приведены рабочие curl-запросы и полный Python-скрипт для seedream-4.5/image-to-image, а также точное описание входных полей (проверено на живом API), использование нескольких референсных изображений и ошибки, с которыми вы реально столкнётесь.

Что вы построите и что для этого нужно

Цель: отправить одно или несколько исходных изображений вместе с инструкцией по редактированию в seedream-4.5/image-to-image и получить URL готового изображения.

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

• API-ключ hiapi — получите его в своей консоли. В каждом запросе ниже он используется как Bearer-токен.
• Исходные изображения должны быть размещены по публично доступным URL. API загружает их на стороне сервера; локальные пути к файлам или приватные URL не подойдут.

Модель работает на асинхронной конечной точке задач: POST /v1/tasks создаёт задачу, GET /v1/tasks/<taskId> сообщает статус, а готовое изображение появляется в data.output[0].url.

Описание входных полей (проверено)

У seedream-4.5/image-to-image есть четыре обязательных входных поля, и другие поля не принимаются — спецификация строгая, неизвестные поля отклоняются с ошибкой 400:

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

На что стоит обратить внимание: параметра n нет (одна задача — один результат; если нужно несколько вариантов, создавайте несколько задач параллельно); и в отличие от image-to-image у seedream-5.0-pro (принимает 1K/2K), версия 4.5 требует 2K или 4K. Отправка 1K сюда вернёт ошибку валидации.

Минимальный рабочий запрос: 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-4.5/image-to-image",
    "input": {
      "prompt": "Turn this product shot into a clean studio photo on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

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

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>"

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

Полный Python-скрипт

SDK не нужен — достаточно requests и цикла опроса:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Создаём задачу
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-4.5/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # публичные URL, максимум 14
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,   # "2K" или "4K"
        },
    }, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    # 2. Опрашиваем до терминального состояния
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}",
                            headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]
            # 3. URL результата истекают -- скачивайте сразу
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in 600s")

png = edit_image(
    "Turn this product shot into a clean studio photo on a seamless white background",
    ["https://your-cdn.example.com/source.jpg"],
)
with open("edited.png", "wb") as f:
    f.write(png)

Обратите внимание на комментарий на шаге 3: URL результата содержат метку времени истечения срока действия. Сразу после успешного завершения задачи сохраняйте байты в своё хранилище — не сохраняйте только возвращённый URL и не рассчитывайте, что он будет работать завтра.

Редактирование с несколькими референсными изображениями

image_urls принимает до 14 изображений в одной задаче. Это отличный инструмент для задач переноса стиля и композиции: передайте изображение, которое хотите отредактировать, вместе с референсными изображениями и опишите в prompt, как их объединить.

{
  "model": "seedream-4.5/image-to-image",
  "input": {
    "prompt": "Apply the color grading and lighting style of the second image to the first image, keep the subject unchanged",
    "image_urls": [
      "https://your-cdn.example.com/subject.jpg",
      "https://your-cdn.example.com/style-reference.jpg"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}

Порядок важен для prompt, но не для API — ссылайтесь на изображения по позиции ("первое изображение", "второе изображение"), чтобы модель знала, какое из них какое.

Замечания для production

Используйте callback вместо опроса. Для любого сценария за пределами скриптов добавьте при создании задачи объект callback на корневом уровне и полностью откажитесь от цикла опроса:

{
  "model": "seedream-4.5/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

По завершении задачи hiapi отправит POST с финальным статусом задачи на ваш URL. Опрос подходит для CLI-инструментов и notebook; для веб-бэкенда правильный выбор — callback, иначе вы будете держать рабочий процесс занятым на десятки секунд, нужных для одной 2K-правки.

Идемпотентность. Создание задачи не идемпотентно — повтор создания после сетевого таймаута может породить (и оплатить) две задачи. Сохраняйте taskId сразу после получения и при повторе сначала проверяйте, нет ли уже активной задачи, прежде чем создавать новую.

Обработка ошибок. Две категории сбоев, с которыми вы столкнётесь в первую очередь:

• 401 permission_denied — неверный ключ или у ключа нет доступа к этой модели. Тело ответа выглядит так: {"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "..."}}. При обращении в поддержку приложите request_id.
• 400 INVALID_REQUEST — нарушение спецификации полей с точным сообщением: неверное значение resolution, более 14 элементов в image_urls, неизвестное поле или image_urls не является массивом. Всё это отлавливается до запуска задачи, поэтому расходов не возникает.

Неудачные задачи сообщают status: "fail" на самой задаче вместе с объектом error — обрабатывайте это как отдельный случай, отличный от HTTP-ошибок, как и делает Python-скрипт выше.

Цены

Стоимость за изображение зависит от разрешения. Актуальные тарифы смотрите на странице цен. Запросы, отклонённые на этапе валидации (400), никогда не запускают задачу, поэтому ошибки в спецификации полей во время интеграции бесплатны.

Связанные материалы

• Страница модели seedream-4.5/image-to-image — песочница, цены и полный справочник параметров
• seedream-4.5/text-to-image — та же серия, генерация только по промпту
• Руководство по seedream-5.0-pro image-to-image — более новый уровень, другое перечисление разрешений
• Документация hiapi — справочник по Task API и аутентификация

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

Можно ли передавать локальный файл или base64-изображение вместо URL? Нет. image_urls должен быть массивом публично доступных URL — платформа загружает и нормализует их на стороне сервера. Сначала загрузите изображения в своё хранилище (S3, R2, любой CDN), затем передайте URL.

Сколько референсных изображений поддерживает seedream-4.5 image-to-image? До 14 на задачу. При превышении возвращается 400 с сообщением, содержащим image_urls: maxItems.

Почему я получаю 400, когда задаю resolution 1K? Конечная точка 4.5 image-to-image принимает только 2K или 4K. Опция 1K относится к image-to-image у seedream-5.0-pro — в разных сериях уровней перечисления различаются.

Можно ли генерировать несколько вариантов в одном запросе? Нет — в спецификации полей нет параметра n, а неизвестные поля отклоняются. Создавайте задачу для каждого варианта и запускайте их параллельно; каждая задача возвращает один результат.

Сколько действует URL результата? URL результата подписаны и имеют срок действия. Сразу после успешного завершения задачи скачивайте изображение и храните его самостоятельно, а не используйте горячие ссылки на вывод задачи.

В чём разница между HTTP-ошибкой и неудачной задачей? HTTP-ошибка (400/401) означает, что запрос так и не стал задачей — исправьте payload или ключ и отправьте снова. Задачи, завершившиеся со status: "fail", были приняты, но не смогли выполниться; причина — в объекте error задачи, и для транзиентных сбоев обычно правильным решением будет повтор с теми же входными данными.